---
title: "Organization customization"
source: https://dev.pageseeder.com/guide/configuration/organization_customization.html
description: "This document describes how to customize PageSeeder server settings through configuration files, including email formatting, UI appearance, legal agreements, and security restrictions for organizations."
last_updated: 2026-08-11T16:36:45+10:00
tokens: ~4029
---

# Organization customization

The organization config modifies the settings of a server to meet typical organizational requirements such as:

- The need for users to accept a legal agreement when logging in.
- The display of a corporate logo in the user interface and email messages.
- Restricting the creation of user accounts by domain name.

> **Note:** This capability is only available on servers with a “Developer” or “Service provider”  license.

## Configuration files

Customizations are determined by the configuration files under the following folder:

```text

pageseeder/webapp/WEB-INF/config/template/[project]/organization
```

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

```text

globalTemplate=[project]
```

The main XML file is:

```text

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

It uses the following structure:

```xml

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

## Email

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”.

> **Note:** To customize the email settings server-wide, set`globalTemplate`in`global.properties`to the name of a project. Without the `globalTemplate` reference, customizations are project specific. 

Example `<email>` config element:

```xml
<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

The following elements are all optional, but any that are used must follow the order listed below. The attributes for each element are required, except for the following:

```text
dkim/@*
```

and

```text
 images/@prefix
```

#### \<dkim\>

To reduce the chance of external email systems treating messages as SPAM, use this element to configure a [<u>DKIM</u>](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) signature. Without a specific configuration, the system signs messages as`pageseeder.com`. Because the message originates from a domain that doesn’t match the signature, it is certain to create warnings or errors from message recipients. Only use this configuration as a short-term solution.

- `@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 example `mail`). *Required if `@domain` is specified.*
- `@disabled` – if `true`, messages are not signed with DKIM.

> **Note:** 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:

```shell
$ openssl genrsa -out email-private-key 2048
```

```shell
$ openssl rsa -in email-private-key -out email-public-key -pubout -outform PEM
```

```shell
$ 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:

```text
config/template/[project]/organization
```

> **Note:** If you copy the file to this location using Linux, to make it readable by PageSeeder use the following command: ```shell $ 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:

```text
   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:

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

Creating, testing and tuning the security settings associated with email can be tedious and risky. There are many sites that can help with this task, but two that we recommend are:

- [uriports.com](https://www.uriports.com/tools), and:
- [mxtoolbox.com](https://mxtoolbox.com/)

#### \<emails\>

This element requires the `@domain` attribute, which is part of the email address on all “from”, “reply to” and other email address fields. On certain messages, this is overridden by `<sender>`.

To use this element requires that messages sent to the domain are forwarded to the PageSeeder server. This can be done by configuring an email server, or an MX record.

For example, the following MX record would forward messages from the `domain="myapp.example.org"` to the PageSeeder server `ps.example.org`.

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

> **Note:** If `domain=""` emails will not include the “reply to” field, so users can’t reply to comments by email.

#### \<sender\>

Requires the `@name` and `@email` attributes as part of the `Sender` header, and some of the `From` headers.

#### \<links\>

[Requires`@prefix`](mailto:Requires@prefix) as part of the email permalinks. Using the example above as a reference, applications built on PageSeeder must either support the following, or redirect users to the equivalent PageSeeder URL, see [email permalinks](/guide/configuration/emails/email_permalinks.md).

- `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 file in the `organization/style` folder. The image must either have a transparent background, or the background must match the `header/@background-color`. See `<style>` below.

The `@prefix` attribute is optional, but if in use, it applies to all images, and the app under the prefix URL must serve all images under the `weborganic/email` folder.

#### \<application\>

Requires the`@name` attribute to replace “PageSeeder” in the text of all emails, and the `@homepage` attribute, which is the home URL of the app.

#### \<footer\>

Requires `@text` to display the footer at the bottom of all messages. This usually includes the organizations address, 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-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  (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:

```xml
<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.

> **Note:** 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. Also any `<!DOCTYPE>` declaration must be removed from the file as this is not supported by PageSeeder.

#### \<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 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](/reference/glossary/markdown.md) format as `terms.md`, `privacy.md`, or `cookies.md`.

```text
config/template/[project]/organization
```

#### \<account-home\>

This element add links and overrides the widgets that appear on the PageSeeder homepage 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 be `small`, `medium` or `large` 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](https://user.pageseeder.com/document/216831.html?publicationid=interface).

## 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:

```xml

<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](https://en.wikipedia.org/wiki/ISO_8601#Durations) format and use ONLY days, hours or minutes. For example, `expiration="P2DT12H"` which translates to 2 days and 12 hours.

#### \<members\>

This element specifies which email domains can create member accounts on the server. It can contain one or more `<email>` elements.

- `<email>` requires a `@domain` attribute, if the domain value has `*.` prefix, it allows the creation of member accounts on sub-domains.

An error is returned to:

- Anyone that tries to create an account using a domain that isn’t on the list.
- Existing members that try to change their address to a domain that isn’t on the list.

> **Note:** Member accounts with a role of [Administrator](/reference/glossary/administrator.md) aren’t restricted by the constraints set in the security elements.