setup
/setup [POST]
| API Support | Available since | Last updated | Output |
|---|---|---|---|
| 4.0100 | 6.0000 | json, xml |
Description
Handles PageSeeder configuration setup.
Usage:
/api/setup /api/setup.xml /api/setup.json
Default database URL
The default database URL is computed as:
| Datebase type | Default database URL |
|---|---|
MySQL | jdbc:mysql://{host}/{database} |
PostgreSQL | jdbc:postgresql://{host}/{database} |
Parameters
The following parameters are always supported by this service.
| Name | Description | Required | Type | Default* |
|---|---|---|---|---|
| updatedatabase | Indicates that the database settings should be updated if equal to 'yes' | no | boolean | false |
| smtpserveraddress | The address of the SMTP server to use | no | string | localhost |
| smtpserverport | SMTP server user port | no | integer | 25 |
| smtpserverusername | SMTP server user name when using authentication | no | string | (empty) |
| smtpserverpassword | SMTP server password when using authentication | no | string | (empty) |
| smtpserverssl | To use SSL to connect to SMTP server | no | boolean | false |
| smtpserverstarttls | To Use StartTLS to connect to SMTP server | no | boolean | false |
| websiteaddress | The host of the URL users access PageSeeder with | no | string | localhost |
| websiteport | The port of the URL users access PageSeeder with | no | integer | 443 |
| websitescheme | The scheme of the URL users access PageSeeder with | no | enum | https |
| emaildomain | The domain for emails sent to PageSeeder (if blank incoming emails are disabled) | no | string | |
| productkey | The PageSeeder product key | no | string | dev |
| projects | The maximum number of projects allowed by the license (integer or 'unlimited') | no | string | unlimited |
| groups | The maximum number of groups allowed by the license (integer or 'unlimited') | no | string | unlimited |
| members | The maximum number of members allowed by the license (integer or 'unlimited') | no | string | unlimited |
| licenseexpires | The date the license expires ('YYYY-MM-DD' or '') | no | date |
* If a default value is specified in this column and setup has been run previously, the default values are the values previously submitted.
Update database
If the updatedatabase parameter is set to true, the following parameters are supported:
| Name | Description | Required | Type | Default* |
|---|---|---|---|---|
| dbtype | The type of database - 'MySQL', 'PostgreSQL' | yes | enum | |
| dbhostname | Where the database is hosted | yes | string | |
| dbname | The name of the database, for example, 'pageseeder' | yes | string | |
| dburl | A custom URL for accessing the database | no | string | Default database URL |
| dbloginname | The new login name to the database server | yes | string | |
| dbloginpassword | The new password to the database server | yes | string | |
| createdatabase | Indicates that the database should be created | no | boolean | false |
| createtables | Indicates that the database tables should be created | no | boolean | false |
Create database
If the createdatabase parameter is set to true , the following parameters are supported to provide the credentials of the database administrator:
| Name | Description | Required | Type | Default |
|---|---|---|---|---|
| dbaloginname | The current database administrator login name | yes | string | |
| dbaloginpassword | The current database administrator password | yes | string |
The database administrator credentials are not stored in PageSeeder – they are only used for creating the PageSeeder database.
Create tables
If the createtables parameter is set to true , the following parameters are supported to provide the details of the PageSeeder administrator to create:
| Name | Description | Required | Type | Default |
|---|---|---|---|---|
| adminfirstname | The first name of the PageSeeder Administrator to create | yes | string | |
| adminsurname | The last name of the PageSeeder Administrator to create | yes | string | |
| adminusername | The username of the PageSeeder Administrator to create | no | string | admin email |
| adminemail | The email of the PageSeeder Administrator to create | yes | string | |
| adminpassword | The password of the PageSeeder Administrator to create | yes | string |
Permission
If the value of DBURL database property is empty, this service can be invoked without authentication as PageSeeder assumes that the setup has not been completed.
Otherwise, only administrators can invoke it.
Response
The response is a reflection of changes made by this service and includes the values from the global and database properties used to set up PageSeeder.
| Field | Description | Type |
|---|---|---|
licenseexpired | If the licenseExpires global property is specified and earlier than today’s date | boolean |
loginrequired | Set to true if the database or administrator details have been modified | boolean |
productkeyinvalid | Set to true if the product key is not valid | boolean |
organizationdisabled | If there is an existing organization config and it is disabled because the product key is not of type "Service provider" | boolean |
organizationerror | If there was an error loading the organization config | boolean |
smtpserveraddress | Value of smtpServerAddress global property | host |
smtpserverpor | Value of smtpServerPort global property | port |
smtpserverusername | Value of smtpServerUsername global property | string |
smtpserverssl | Value of smtpServerSSL global property | boolean |
smtpserverstarttls | Value of smtpServerSTARTTLS global property | boolean |
productkey | Value of productKey global property | string |
projects | Value of projects global property, a number or unlimited (default to unlimited), | string |
groups | Value of groups global property, a number or unlimited (default to unlimited) | string |
members | Value of members global property, a number or unlimited (default to unlimited) | string |
licenseexpires | Value of licenseExpires global property | date |
websiteaddress | Value of webSiteAddress global property | host |
websitescheme | Value of webSiteScheme global property | string |
websiteport | Value of webSitePort global property | port |
emaildomain | Value of emailDomain global property | host |
dbtype | Value of DatabaseType database property | string |
dbhostname | Value of HostName database property | host |
dbname | Value of DatabaseName database property | string |
dbloginname | Value of LoginName database property | string |
dburldefault | A computed value based on the database properties | string |
dburl | Value of DBURL database property | string |
dburldefault is used as the default value for the database URL. So if you don’t edit the DBURL, it should be identical to dburl.Sample XML response
/api/setup.xml
<setup> <licenseexpired>false</licenseexpired> <loginrequired>false</loginrequired> <productkeyinvalid>false</productkeyinvalid> <organizationdisabled>false</organizationdisabled> <organizationerror>false</organizationerror> <smtpserveraddress>mail.example.org</smtpserveraddress> <smtpserverport>25</smtpserverport> <smtpserverusername/> <smtpserverssl>false</smtpserverssl> <smtpserverstarttls>false</smtpserverstarttls> <productkey>dev</productkey> <projects>unlimited</projects> <groups>unlimited</groups> <members>unlimited</members> <licenseexpires/> <websiteaddress>localhost</websiteaddress> <websitescheme>http</websitescheme> <websiteport>8080</websiteport> <emaildomain>localhost</emaildomain> <dbtype>MySQL</dbtype> <dbhostname>sample-db</dbhostname> <dbname>pageseeder</dbname> <dbloginname>pageseeder</dbloginname> <dburldefault>jdbc:mysql://sample-db/pageseeder</dburldefault> <dburl>jdbc:mysql://sample-db/pageseeder</dburl> </setup>
Sample JSON response
/api/setup.json
In JSON, values are returned as strings, unless they are boolean values that are not global properties. For example, port numbers are returned as strings.
{
"licenseexpired":false,
"loginrequired":false,
"productkeyinvalid":false,
"organizationdisabled":false,
"organizationerror":false,
"smtpserveraddress":"mail.example.org",
"smtpserverport":"25",
"smtpserverusername":"",
"smtpserverpassword":"",
"smtpserverssl":"false",
"smtpserverstarttls":"false",
"productkey":"dev",
"projects":"unlimited",
"groups":"unlimited",
"members":"unlimited",
"licenseexpires":"",
"websiteaddress":"localhost",
"websitescheme":"http",
"websiteport":"8080",
"emaildomain":"localhost",
"dbtype":"MySQL",
"dbhostname":"sample-db",
"dbname":"pageseeder",
"dbloginname":"pageseeder",
"dburldefault":"jdbc:mysql://sample-db/pageseeder",
"dburl":"jdbc:mysql://sample-db/pageseeder"
}Error handling
| HTTP status code | Error condition |
|---|---|
| 400 | One or more parameters is missing |
| 400 | The database login password is not strong (create database only) |
| 400 | The invalid administrator email address (creating tables only) |
| 400 | Administrator password cannot be empty (creating tables only) |
| 400 | Administrator password is too weak (creating tables only) |
| 400 | Administrator password is the same as the username (creating tables only) |
| 400 | Administrator username is invalid (creating tables only) |
| 400 | SMTP server port is invalid |
| 400 | PageSeeder cannot connect to mail server |
| 400 | Invalid database, cannot retrieve database version (updating database only) |
| 400 | Database version does not match current version (updating database only) |
| 401 | If PageSeeder is already configured and the user is not authenticated |
| 403 | If PageSeeder is already configured and the user is not an administrator |