Skip to main content

 Services

Web services from /about to /webhooks

setup

/setup [POST]

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 typeDefault database URL
MySQL jdbc:mysql://{host}/{database}
PostgreSQL jdbc:postgresql://{host}/{database} 

Parameters

The following parameters are always supported by this service.

NameDescriptionRequiredTypeDefault*
updatedatabaseIndicates that the database settings should be updated if equal to 'yes'nobooleanfalse
smtpserveraddressThe address of the SMTP server to usenostringlocalhost
smtpserverportSMTP server user portnointeger25
smtpserverusernameSMTP server user name when using authenticationnostring(empty)
smtpserverpasswordSMTP server password when using authenticationnostring(empty)
smtpserversslTo use SSL to connect to SMTP servernobooleanfalse
smtpserverstarttlsTo Use StartTLS to connect to SMTP servernobooleanfalse
websiteaddressThe host of the URL users access PageSeeder withnostringlocalhost
websiteportThe port of the URL users access PageSeeder withnointeger443
websiteschemeThe scheme of the URL users access PageSeeder withnoenumhttps
emaildomainThe domain for emails sent to PageSeeder (if blank incoming emails are disabled)nostring
productkeyThe PageSeeder product keynostringdev
projectsThe maximum number of projects allowed by the license (integer or 'unlimited')nostringunlimited
groupsThe maximum number of groups allowed by the license (integer or 'unlimited')nostringunlimited
membersThe maximum number of members allowed by the license (integer or 'unlimited')nostringunlimited
licenseexpiresThe date the license expires ('YYYY-MM-DD' or '')nodate

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

NameDescriptionRequiredTypeDefault*
dbtypeThe type of database - 'MySQL', 'PostgreSQL'yesenum
dbhostnameWhere the database is hostedyesstring
dbnameThe name of the database, for example, 'pageseeder'yesstring
dburlA custom URL for accessing the databasenostringDefault database URL
dbloginnameThe new login name to the database serveryesstring
dbloginpasswordThe new password to the database server yesstring
createdatabaseIndicates that the database should be creatednobooleanfalse
createtablesIndicates that the database tables should be creatednobooleanfalse

Create database

If the createdatabase parameter is set to true , the following parameters are supported to provide the credentials of the database administrator:

NameDescriptionRequiredTypeDefault
dbaloginNameThe current database administrator login nameyesstring
dbaloginpasswordThe current database administrator passwordyesstring

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:

NameDescriptionRequiredTypeDefault
adminfirstnameThe first name of the PageSeeder Administrator to createyesstring
adminsurnameThe last name of the PageSeeder Administrator to createyesstring
adminusernameThe username of the PageSeeder Administrator to createnostringadmin email
adminemailThe email of the PageSeeder Administrator to createyesstring
adminpasswordThe password of the PageSeeder Administrator to createyesstring

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.

FieldDescriptionType
licenseexpiredIf the licenseExpires global property is specified and earlier than today’s dateboolean
loginrequiredSet to true if the database or administrator details have been modifiedboolean
productkeyinvalidSet to true if the product key is not validboolean
organizationdisabled If there is an existing organization config and it is disabled because the product key is not of type "Service provider"boolean
organizationerrorIf there was an error loading the organization configboolean
smtpserveraddressValue of smtpServerAddress global propertyhost 
smtpserverporValue of smtpServerPort global propertyport 
smtpserverusernameValue of smtpServerUsername global propertystring
smtpserversslValue of smtpServerSSL global propertyboolean
smtpserverstarttlsValue of smtpServerSTARTTLS global propertyboolean
productkeyValue of productKey global propertystring 
projectsValue of projects global property, a number or unlimited (default to unlimited), string 
groupsValue of groups global property, a number or unlimited (default to unlimited)string 
membersValue of members global property, a number or unlimited (default to unlimited)string 
licenseexpiresValue of licenseExpires global propertydate
websiteaddressValue of webSiteAddress global propertyhost 
websiteschemeValue of webSiteScheme global propertystring
websiteportValue of webSitePort global propertyport
emaildomainValue of emailDomain global propertyhost
dbtypeValue of DatabaseType database propertystring
dbhostnameValue of HostName database propertyhost
dbnameValue of DatabaseName database propertystring
dbloginnameValue of LoginName  database propertystring
dburldefaultA computed value based on the database propertiesstring
dburlValue of DBURL database propertystring
The 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 codeError condition
400One or more parameters is missing
400The database login password is not strong (create database only)
400The invalid administrator email address (creating tables only)
400Administrator password cannot be empty (creating tables only)
400Administrator password is too weak (creating tables only)
400Administrator password is the same as the username (creating tables only)
400Administrator username is invalid (creating tables only)
400SMTP server port is invalid
400PageSeeder cannot connect to mail server
400Invalid database, cannot retrieve database version (updating database only)
400Database version does not match current version  (updating database only)
401If PageSeeder is already configured and the user is not authenticated
403If PageSeeder is already configured and the user is not an administrator
Created on , last edited on