Jump to

• Request
• Response

Expire Sites

post

/sites/management/api/v1/sites/_expire

EXTENDED OPERATION

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

Email notifications can be suppressed by providing a suppress notifications request header. Presence of this request header will stop any email notifications being generated during site expiration processing initiated by the request containing the header.

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.

Polling the status of an asynchronous request requires the use of sessions. Ensure that any 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

Supported Media Types

• application/json

Header Parameters

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

Body ()

Site expiration overrides. If no body is provided the default service wide site expiration settings are used.

Root Schema : SiteExpirationSettings

Type: 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.

Show Source

• 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

  Introduced in release 20.3.1.
• 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.

{
    "description":"<p>Site expiration related settings, such as enabling or disabling automatic site deactivation and deletion. Site expiration only takes affect if site governance is enabled.</p><small>Introduced in release 20.3.1.</small>",
    "properties":{
        "action":{
            "description":"<p>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.</p><p>Valid values are:\n<ul><li> <code>nothing</code> - Site is left online and is not deleted</li><li> <code>deactivate</code> - Site is taken offline when the site expires</li><li> <code>delete</code> - Site is taken offline when the site expires and deleted after a configurable number of days after expiration</li></p><small>Introduced in release 20.3.1.</small>",
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"string"
        },
        "deleteAfter":{
            "description":"<p>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. </p><small>Introduced in release 20.3.1.</small>",
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"integer",
            "format":"int32",
            "maximum":90,
            "minimum":3
        }
    }
}

Back to Top

Response

202 Response

Accepted

303 Response

See Other

400 Response

Bad Request

401 Response

Unauthorized

403 Response

Forbidden

409 Response

Conflict

Body ()

Root Schema : schema

Match All

Show Source

• allOf GovernanceDisabledExceptionDetail

{
    "allOf":[
        {
            "$ref":"#/definitions/GovernanceDisabledExceptionDetail"
        }
    ]
}

Nested Schema : GovernanceDisabledExceptionDetail

Match All

Show Source

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

{
    "description":"",
    "allOf":[
        {
            "$ref":"#/definitions/ExceptionDetail"
        },
        {
        }
    ]
}

Nested Schema : ExceptionDetail

Type: 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.

Show Source

• 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 or detail.

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

{
    "description":"<p>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.</p>",
    "properties":{
        "type":{
            "description":"<p>Absolute URI that identifies the problem type. When this URI dereferenced, it <strong>should</strong> provide a human-readable summary of the problem, for example, as a HTML page.</p>",
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"string",
            "format":"uri"
        },
        "title":{
            "description":"<p>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 <code>o:errorCode</code> for this purpose.</p>",
            "x-multiLingual":true,
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"string"
        },
        "status":{
            "description":"<p>Corresponding HTTP status code for the error.</p>",
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"integer",
            "format":"int32"
        },
        "detail":{
            "description":"<p>Description specific to this occurrence of the problem. The human-readable, potentially multi-line details describing the problem in more details.</p>",
            "x-multiLingual":true,
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"string"
        },
        "instance":{
            "description":"<p>URI to the link that provides more detail about the error.</p>",
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"string",
            "format":"uri"
        },
        "o:errorCode":{
            "description":"<p>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 <code>title</code> or <code>detail</code>.</p>",
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"string"
        },
        "o:errorPath":{
            "description":"<p>XPath or JSON path to indicate where the error occurs.</p>",
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"string"
        },
        "o:errorDetails":{
            "description":"<p>Multiple errors can be organized in a hierarchical structure.</p>",
            "x-returnedIn":[
                "representation",
                "default",
                "basic"
            ],
            "type":"array",
            "items":{
                "allOf":[
                    {
                        "$ref":"#/definitions/ExceptionDetail"
                    }
                ]
            }
        }
    }
}

Nested Schema : o:errorDetails

Type: array

Multiple errors can be organized in a hierarchical structure.

Show Source

• Array of: items

{
    "description":"<p>Multiple errors can be organized in a hierarchical structure.</p>",
    "x-returnedIn":[
        "representation",
        "default",
        "basic"
    ],
    "type":"array",
    "items":{
        "allOf":[
            {
                "$ref":"#/definitions/ExceptionDetail"
            }
        ]
    }
}

Nested Schema : items

Match All

Show Source

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

{
    "allOf":[
        {
            "$ref":"#/definitions/ExceptionDetail"
        }
    ]
}

Example Response (Site Governance Disabled)

{
    "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"
}

413 Response

Payload Too Large

415 Response

Unsupported Media Type

429 Response

Too Many Requests

500 Response

Internal Server Error

501 Response

Not Implemented

502 Response

Bad Gateway

503 Response

Service Unavailable

504 Response

Gateway Timeout

Back to Top