Expire Sites
/sites/management/api/v1/sites/_expire
Perform site expiration processing such as taking the site offline or deleting a site if the site has expired. If site governance is enabled and a site has an expiration date set then the site can be taken offline or deleted based on the service defined site expiration settings. Executing this method will perform this processing, potentially doing nothing if the site has not yet expired, taking the site offline if the site is expired and the site is online or deleting the site if the site has expired and gone passed the "delete after" period. This method examines all sites that have expired.
Introduced in release 20.3.2.
Authorization
To invoke this operation, the authenticated user or client application must have one of the following roles:
- CECSitesAdministrator
Email Notifications
Email notifications are sent to the site managers and site owners at various points in the life-cycle for a site that is due to expire. Site administrators are also send an email in the cases where a site cannot be deactivated or deleted. If the site has more than fifty users, applications or groups with the manager role then the first fifty will receive an email. When site expiration processing is executed email notifications are sent:
- When a site expires in 30 days
- When a site expires in 5 days
- When a site expires in 1 day
- When a site expires and is taken offline
- When a site expires and cannot be taken offline
- When a site has expired and is due to be deleted in 3 days
- When a site has expired and is deleted
- When a site has expired and cannot be deleted
Site Governance
Site expiration can only be used when site governance is enabled. If site governance is disabled a site expiration processing request will be rejected.
Change Expiration Settings
By default this method uses the service defined site expiration settings. These settings can be changed.
For more information, see Update the Site Management Settings.
Extending the Expiration Date of a Site
Site owners or managers can use the extend operation to extend the expiration date of a site to stop it being deactivated or deleted.
For more information, see Extend the Expiration Period for a Site.
Asynchronous Processing
This operation only supports asynchronous processing. A Prefer
header with the value of respond-async
must be included in the request. An accepted response will include a Location
header, which provides the location of a status resource that can be polled to obtain information about the asynchronous processing. The suggested interval to poll for the results is 1000 milliseconds. The polling interval is also returned when reading the status resource response. Status information will be available for 5000 milliseconds after the asynchronous request has completed. After this time the status for this asynchronous request will response with not found.
Set-Cookie
response headers are included in the Cookie
header for the request that reads the status.For more information about reading the status see Get the Progress of a Site Related Job.
Successful Response Examples
This operation responds with the following success (2xx) responses. For a full list of response HTTP status codes and example bodies, consult the Response section of this operation.
202Accepted - Site Expiration Processing Started
When the site expiration is executed asynchronously the request will be accepted, then the progress of the request can be monitored by reading the job status resource that is provided in the response Location
header.
Redirection Response Examples
This operation responds with the following redirection (3xx) responses. For a full list of response HTTP status codes and example bodies, consult the Response section of this operation. Note: Depending on the client technology used to invoke this operation a 2xx response may be returned if the redirection is followed automatically.
303See Other - Expire Sites Using the Service Defaults
Execute the site expiration processing for all sites using the service defined settings.
Request
POST https://api.example.com/sites/management/api/v1/sites/_expire
Request Headers
Prefer=respond-async
303See Other - Deactivate expired Sites
Execute the site expiration processing requesting sites are deactivated if required.
Request
POST https://api.example.com/sites/management/api/v1/sites/_expire
Request Headers
Prefer=respond-async
Request Body
{ "action": "deactivate", "deleteAfter": 5 }
303See Other - Delete Expired Sites
Execute the site expiration processing requesting sites are deactivated. A site will also be deleted if the site expired more than three days ago.
Request
POST https://api.example.com/sites/management/api/v1/sites/_expire
Request Headers
Prefer=respond-async
Request Body
{ "action": "delete", "deleteAfter": 3 }
Client Error Response Examples
This operation responds with the following client error (4xx) responses, with exception details in the response body or reported through the asynchronous job. For a full list of response HTTP status codes and example bodies, consult the Response section of this operation.
409Conflict - Site Governance Disabled
Site governance is enabled or disabled using a tenant-wide setting controlled by site administrators. When site governance is disabled, certain methods will be prevented on the site management REST API, such as creating a request for a site or activating a site.
Error Code
OCE-SITEMGMT-009002
Resolution - Enable Site Governance
Enable governance for sites using the Sites and Assets administrator settings and retry the failed request.
Where This Error Can be Returned
- This error can be returned in the response body.
- This error can be returned in the asynchronous job status.
Example Response Body
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1", "title": "Site Governance Disabled", "status": "409", "detail": "A request to create or copy a site cannot be processed when site governance is disabled.", "o:errorCode": "OCE-SITEMGMT-009002" }
Request
- application/json
-
Prefer(optional): string
Request asynchronous processing of the request using a
respond-async
header value. -
X-Suppress-Notifications(optional): boolean
If a client wants to prevent notifications being sent on a per request basis this header can be set to the value
true
. Even if the notification would normally be sent, this header will suppress notification delivery for the request.
Site expiration overrides. If no body is provided the default service wide site expiration settings are used.
object
Site expiration related settings, such as enabling or disabling automatic site deactivation and deletion. Site expiration only takes affect if site governance is enabled.
Introduced in release 20.3.1.-
action(optional):
string
What action to take when the site expires. This can be do nothing. If the site is online the site will remain online. The deactivate action takes the site offline after the site expires. The delete action takes the site offline after the site expires and also deletes the site. The site is deleted using the days after to determine how long after expiration before the site is deleted.
Valid values are:
-
nothing
- Site is left online and is not deleted -
deactivate
- Site is taken offline when the site expires -
delete
- Site is taken offline when the site expires and deleted after a configurable number of days after expiration
-
-
deleteAfter(optional):
integer(int32)
Minimum Value:
3
Maximum Value:90
Number of days to wait after a site expires before deleting the site. This setting is only used if the action selected is to delete expired sites. This setting can still be set if site deletion is disabled; the setting value will just be ignored.
Introduced in release 20.3.1.
Response
202 Response
303 Response
400 Response
401 Response
403 Response
409 Response
-
object
ExceptionDetail
In addition to HTTP error code and error messages, it is often desirable to provide additional information to the client when a request fails. In such cases, the additional information will be included in the response body.
-
object
In addition to HTTP error code and error messages, it is often desirable to provide additional information to the client when a request fails. In such cases, the additional information will be included in the response body.
-
detail(optional):
string
Description specific to this occurrence of the problem. The human-readable, potentially multi-line details describing the problem in more details.
-
instance(optional):
string(uri)
URI to the link that provides more detail about the error.
-
o:errorCode(optional):
string
Application error code, which is different from HTTP error code. This code should be used to check for specific errors, rather than comparing fields such as the
title
ordetail
. -
o:errorDetails(optional):
array o:errorDetails
Multiple errors can be organized in a hierarchical structure.
-
o:errorPath(optional):
string
XPath or JSON path to indicate where the error occurs.
-
status(optional):
integer(int32)
Corresponding HTTP status code for the error.
-
title(optional):
string
Short, human-readable summary of the problem. It is not advisable to use the title as a way of checking for specific errors, use the
o:errorCode
for this purpose. -
type(optional):
string(uri)
Absolute URI that identifies the problem type. When this URI dereferenced, it should provide a human-readable summary of the problem, for example, as a HTML page.
array
Multiple errors can be organized in a hierarchical structure.
-
object
ExceptionDetail
In addition to HTTP error code and error messages, it is often desirable to provide additional information to the client when a request fails. In such cases, the additional information will be included in the response body.
{
"type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
"title":"Site Governance Disabled",
"status":"409",
"detail":"A request to create or copy a site cannot be processed when site governance is disabled.",
"o:errorCode":"OCE-SITEMGMT-009002"
}