This topic provides information about trigger requests and trigger messages.
for more information. Communication with the triggered cache manager function is done using HTTP 1.0 protocol. The HTTP POST method is used to send trigger messages to the triggered cache manager function (unless otherwise noted). The Content-Length header is required on all POST requests. The header Content-Type may be set to application/x-trigger-request, but is not required. All other request headers are ignored.
The contents of a POST request should not be URL encoded. Each line of the POST request describes an independent trigger message. A single logical operation is associated with each trigger message. Any line that begins with a pound sign (#) is treated as a comment line and is ignored.
Trigger messages are issued by writing a program to submit them using the HTTP 1.0 protocol. You should write a program to issue a POST similar to the following:
POST /handler/ HTTP/1.0
Content-Type: application/x-trigger-request
Content-length: nn
-id trigid1 -qp A -update -from /item1.html -to /item1.html
Where:
The following tasks (organized by trigger handler) are supported using trigger messages. Trigger messages are plain text printable strings. Trigger messages generally consist of keywords and associated values. Keywords may be abbreviated to the shortest unambiguous string. Optional letters are specified within square brackets. For example, -fo[rce] indicates that any of the following are valid: -fo, -for, -forc, or -force.
Use this trigger message to stop the triggered cache manager function. Terminating the triggered cache manager function may result in significant delays during restart.
-id trigid -term[inate]
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -term[inate] | No value. |
See Trigger responses.
Use this trigger message to monitor the status of request queues.
-id trigid -q[ueues]
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -qu[eues] | No value. |
This trigger message returns one line per request queue, where each line has the following format:
1140 id internalid admin ! description-name: active=nn queued=mm lifetime-total=tt lifetime-failed=ff lifetime-retried=rr threads=numt
| Response | Description |
|---|---|
| 1140 | The message ID 1140, response to query request queues. |
| id | The trigger ID from the query or the internally generated trigger ID if -id was omitted from the query. |
| internalid | The internally generated trigger id. |
| description-name | The name of the configuration description whose request queue this line pertains to. |
| nn | The number of requests in this request queue that are currently processing. |
| mm | The number of requests in this request queue that are waiting to be processed. |
| tt | The number of total requests processed by this request queue since the triggered cache manager function was last started. |
| ff | The total number of requests which were processed and failed by this request queue since the triggered cache manager function was last started. |
| rr | The total number of requests which were processed and retried by this request queue since the triggered cache manager function was last started. |
| numt | The number of threads used to handle this request queue. This number remains constant unless the triggered cache manager function is restarted and the configuration was changed to specify more threads. For example: 1140 6 6 admin ! publishapp: active=5 queued=7 lifetime-total=98770 lifetime-failed=0 lifetime-retried=0 threads=10 |
See Trigger responses.
Use this trigger message to start logging messages to the configured log.
-id trigid -startlog
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -startlog | No value. |
See Trigger responses.
Use this trigger message to stop logging messages to the log.
-id trigid -stoplog
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -stoplog | No value. |
See Trigger responses.
Use this trigger message to roll over the log. The current log file is closed, .old is appended to the file name, and a new file is started.
-id trigid -rolllog
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -rolllog | No value. |
See Trigger responses.
Use this trigger message to purge an asynchronous request that has not yet completed. Note that it may not be possible to immediately purge a request if the request is in a state which must complete before it can be removed from the system. When a purge trigger message arrives, the specified request is marked purged and it is deleted from the system at the first available synchronization point.
-id trigid -purge triggerid
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -purge | The internal ID assigned to the request. The internal ID is returned to the requester as part of the response when the trigger message is accepted and can also be found in the logs. |
See Trigger responses.
Use these trigger messages to find the status of all trigger messages or a particular trigger message. You can query all trigger messages or query a specific trigger message.
-id trigid -qa[ll]
-id trigid -qt[rigger] triggerid
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique id is used. |
| -qa[ll] | No value. Queries all trigger messages. |
| -qt[rigger] | The internal ID assigned to the request. The internal ID is returned to the requester as part of the response when the trigger message is accepted and can also be found in the logs. |
The following message is returned as one line for each trigger message, where each line has the following format:
1151 id internalid admin ! trigger-id trigger-internalid handler state queue-policy collapsed-id purged
| Response | Description |
|---|---|
| 1151 | The message ID 1151, response to a query trigger message. |
| id | The trigger ID from the query or the internally generated trigger ID if -id was omitted from the query. |
| internalid | The internally generated trigger id. |
| trigger-id | The trigger ID from the trigger message. |
| handler | The name of the trigger handler. |
| state | The state of the trigger message. |
| queue-policy | The queue policy specified on the trigger message. See Queue policy. |
| collapsed-id | The internal identifier of the trigger message into which this request has been collapsed, if the request has been collapsed. |
| purged | The word purged, if the request has been purged. For example: 1151 DaedalusCtl 212 admin ! trg65 180 updates Collapsed A 160 purged. |
See Trigger responses.
Any cache target can be enabled or disabled without shutting down the triggered cache manager function. If a cache target is disabled, no data is sent to the cache target, and all other actions proceed as normal.
-id trigid -chsi[nk] target {e[nable]|d[isable]}
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique id is used. |
| -chsi[nk] | The name of the cache target to enable or disable. |
| {e[nable]|d[isable]} | Specify enable to enable the cache target. Specify disable to disable the cache target. |
See Trigger responses.
Any acknowledgement target can be enabled or disabled without shutting down the triggered cache manager function. If an acknowledgement target is disabled, no requests are sent to the acknowledgement target, and the system acts as if the request was successfully sent.
-id trigid -chac[k] acknowledgement {e[nable]|d[isable]}
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique id is used. |
| -chac[k] | The name of the acknowledgement to enable or disable. |
| {e[nable]|d[isable]} | Specify enable to enable the acknowledgement. Specify disable to disable the acknowledgement. |
See Trigger responses.
The cache target priority associated with an Update Cache trigger handler can be changed without shutting down the triggered cache manager function.
id trigid -chsp[riority] handler num
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique id is used. |
| -chsp[riority] | The name of the trigger handler and the new value for the cache target priority. |
See Trigger responses.
Use these messages to copy a single object (optionally renaming the object) or copy a list of objects from a data source to a cache target.
-id trigid -qp[olicy] queue-policy -ob[jects] object-list
-id trigid -qp[olicy] queue-policy -up[date] -fr[om] source-d -to target-id
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -qp[olicy] | Optional. See Queue policy. |
| -ob[jects] | Specifies a list of objects delimited by a space. Paths are relative to the cache target directory defined in your configuration. For example: -ob item1.html item2.html /dir3/item3.html. |
| -up[date] | No value. |
| -fr[om] | Required if -update is specified. Any printable string that specifies the name of the source object. |
| -to | Optional, defaults to the value specified by -to. Any printable string that specifies the name of the cache target object. |
See Trigger responses.
Use these messages to delete cache target objects.
-id trigid -qp[olicy] queue-policy -de[elete] object
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -qp[olicy] | Optional. See Queue policy. |
| -de[lete] | Specifies the object to delete. |
See Trigger responses.
Use this message to move data from one or more data sources, construct pages, and write constructed pages to one or more targets. This message inputs a set of object names. The objects are copied from a data source and all other objects that have been defined as dependent upon the input objects are added to this set. All objects are then assembled and copied to the cache target. Object dependencies are identified through an object dependency graph (ODG).
-id trigid -qp[olicy] queue-policy -ob[jects] itemlist
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -qp[olicy] | Optional. See Queue policy. |
| -ob[jects] | Specifies a list of objects delimited by a space. Paths are relative to the cache target directory defined in your configuration. For example: -ob item1.html item2.html /dir3/item3.html. |
See Trigger responses.
Use this message to write the current state of the ODG into a text format. A file named snapshot.log is created in the directory containing the specified ODG.
-id trigid -dos[napshot]
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -dos[napshot] | No value. |
See Trigger responses.
Use this message to add an object to the ODG.
-id trigid -ao[bject] objectid
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -ao[bject] | Specifies the name of the object to add. |
See Trigger responses.
Use these messages to delete an object from the ODG.
-id trigid -dob[ject] objectid
-id trigid -dob[ject] objectid -fo[rce]
-id trigid -dob[ject] objectid -dor[phans]
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -dob[ject] | Specifies the name of the object to delete. |
| -fo[rce] | Optional. No value. Specifies that all edges connected to the object are removed and the object is removed. |
| -dor[phans] | Optional. No value. Specifies that all edges connected to the object are removed, the object is removed, and orphaned objects are removed. |
See Trigger responses.
Use these messages to add an edge to the ODG.
-id trigid -ae[dge] -fr[om] from-object -to to-object -ed[getype] composition
-id trigid -ae[dge] -fr[om] from-object -to to-object -ed[getype] composition -fo[rce]
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -ae[dge] | No value. |
| -fr[om] | Specifies the file name of the independent object. |
| -to | Specifies the file name of the dependent object. |
| -ed[getype] | Must be composition. |
| -fo[rce] | Optional. No value. Specifies that any necessary endpoints are added and then the edge is added. |
See Trigger responses.
Use these messages to delete an edge from the ODG.
-id trigid -de[dge] -fr[om] from-object -to to-object -ed[getype] composition
-id trigid -de[dge] -fr[om] from-object -to to-object -ed[getype] composition -dor[phans]
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -de[dge] | No value. |
| -fr[om] | Specifies the file name of the independent object. |
| -to | Specifies the file name of the dependent object. |
| -ed[getype] | Must be composition. |
| -dor[phans] | Optional. No value. Specifies that the edge is removed and orphaned endpoints are removed. |
See Trigger responses.
Use this message to retrieve a list of all orphaned objects.
-id trigid -qo[rphans]
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -qo[rphans] | No value. |
See Trigger responses.
Use this message to query an object for a list of all objects that this object is dependent upon.
-id trigid -qdependen[cies] object -ed[dgetype] composition
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -qdependen[cies] | Specifies the name of the object to query. |
| -ed[dgetype] | Must be composition. |
See Trigger responses.
Use this message to query an object fo a list of all objects that are dependent upon this object.
-id trigid -qdependen[ts] object -ed[dgetype] composition
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -qdependen[ts] | Specifies the name of the object to query. |
| -ed[dgetype] | Must be composition. |
See Trigger responses.
Use this message to return the list of all dependencies of the objects in the object list. This query returns a list of all the objects that might be affected if all of the objects in the object list were triggered to a Publish trigger handler.
-id trigid -qc[hain] list -ed[dgetype] composition
| Keyword | Description |
|---|---|
| -id | Optional. Any printable string and is used for identification in the logs and within messages. If not specified, an internally generated unique ID is used. |
| -qc[hain] | Specifies a list of objects delimited by a space. |
| -ed[dgetype] | Must be composition. |
See Trigger responses.
Use a GET request with the following URL to retreive an object out of the object dependency graph (ODG) repository.
/odg-name/{source|assembled}/object-name
| Keyword | Description |
|---|---|
| odg-name | The name of the ODG description in the configuration. |
| {source|assembled} | Specify source to indicate that the original data should be returned. Specify assembled to indicate that the assembled version of the object should be returned. |
| object-name | The name of the object. |
The Content-Length: response header record is returned. If the specified URL is not valid, status code 404 is returned. A URL may not be valid for any of the following reasons:
See Trigger responses.
Some trigger messages may specify a queuing policy. A queuing policy refers to how asynchronous trigger messages are sequenced through the request queues. There are three different queuing policies: A, S, and P. Trigger messages queued under policy A (asynchronous) are processed independently of each other and generally in parallel of each other. Trigger messages queued under policy S or P (sequential or parallel) are logically grouped into a dependent group consisting of at least one S trigger message and zero or more P trigger messages. For example, trigger messages may arrive in groups which can be visualized in either of the two following ways:
trailing-S group) PPPPPPPS PPS PPPPS S PPS (leading -S group) SPPPPPPP SPPPPPP SPPPPPP S SPP
Sets of consecutive P trigger messages are processed in parallel, but while any type P trigger message is being processed, no type S trigger message may be started. Once a type S trigger message has started, no type P trigger message may start. For any queue, there is at most one type S trigger message processed at any time. For any queue, no type S trigger message is being processed if a type P trigger message is being processed. Type A trigger messages are processed regardless of the current state of type S or P trigger messages.
Note that because the request queues are associated with trigger handler descriptions, you may have multiple S and P streams processing in parallel, so long as the incoming trigger messages are directed to different trigger handlers.
Responses are sent when a trigger message is received and as an acknowledgement message. The format of the response is:
sss text Content-Length: nn Content-Type: application/x-trigger-msglist mmmm requestors-requestid internal-requestid handlerid ! data\r\n
Where:
Some handlers process trigger messages asynchronously. The initial response to asynchronous trigger messages is to indicate a status code of 202. Final status is provided through an acknowledgement message sent to an acknowledgement target.
The general status codes may be sent in response to any trigger message. Handler specific status codes are listed for status codes that have a more specific meaning.
| Value | Meaning | Example of cause or use |
|---|---|---|
| 200 | The request was completed successfully |
Queries |
| 202 | The request has been accepted for processing. There may be an asynchronous response later. |
Publish trigger handlers |
| 400 | Client error, handler specific. The returned text body may contain more information. |
Malformed POST |
| 404 | Cannot find URL requested. |
Handler does not exist |
| 500 | Server error, handler specific. The returned text body may contain more information. |
Publish errors |
| 501 | Specified HTTP command not implemented. |
HEAD, PUT |
| Value | Meaning |
|---|---|
| 202 | Success. The command response is in the body. |
| 400 | Failure. The request syntax is wrong. |
| Value | Meaning |
|---|---|
| 202 | Success. The trigger message is queued for processing. |
| 400 | Failure. The request syntax is wrong. |
| Value | Meaning |
|---|---|
| 202 | Success. The operation is queued for processing. |
| 400 | Failure. The request syntax is wrong. |
| Value | Meaning |
|---|---|
| 200 | Success. The operation is complete, with possible warnings. |
| 400 | Failure. The requested syntax is wrong. |
| Code | Meaning |
|---|---|
| 1101 | {0} (Successful acknowledgement of queued trigger message. The data consists of the list of objects that are rebuilt) |
| 1102 | {0} request is queued (The trigger message was successfully queued) |
| 1104 | Server terminated |
| 1105 | Log roll-over successful |
| 1106 | Logging has been enabled |
| 1107 | Logging has been disabled |
| 1108 | Request "{0}" will be purged |
| 1109 | Specified object "{0}" has been deleted from ODG "{1}" |
| 1110 | Object "{0}" defined in ODG "{1}" |
| 1111 | Edge "{0}" to :{1}" was deleted from ODG "{2}" |
| 1113 | Edge "{0}" to "{1}" was added in ODG "{2}" |
| 1114 | Collapsed requests {0} will also be purged |
| 1115 | Server will terminate after active asynchronous request have completed |
| 1120 | Snapshot for {0} successful |
| 1140 | {0}: active={1} queued={2} lifetime-total={3} lifetime-failed={4} lifetime-retried={5} threads={6} |
| 1141 | Lifetime total server requests={0} |
| 1150 | No active requests. |
| 1151 | {0} {1} {2} {3} {4} {5} |
| 1152 | Version: {0} Started: {1} |
| 1160 | {0} {1} {2} |
| 1161 | {0} |
| 1162 | {0} |
| 1170 | ={0} "{1}" has been changed |
| 1171 | {0} "{1}" has been changed to have cache target priority {2} |
| 2102 | A value for the "{0}" flag was specified and will be ignored |
| 2103 | Changed "{0}" to "/{0}" because all names specified on the command line must be absolute |
| 2104 | Error saving request to disk, request will not be recovered over restart |
| 2105 | Error rolling log |
| 2106 | Logging already enabled |
| 2107 | Logging already disabled |
| 2108 | Duplicate object "{0}" will be ignored |
| 2110 | Server is in the process of being shutdown. This request will not be executed until the server is restarted. |
| 2115 | No value found for the "{0}" flag. The flag has been ignored |
| 2116 | Value "{0}" for "{1}" keyword will be ignored |
| 2117 | Specification of the "{0}" keyword was done twice, "{1}" ignored |
| 9011 | Error reading "{0}" from data source specified in description "{1}" {2} |
| 9012 | Error writing "{0}" to cache target specified in description "{1}" {2} |
| 9013 | Error sending acknowledgment to acknowledgment specified in description "{0}" {1} |
| 9014 | Error erasing "{0}" from cache target specified in description "{1}" {2} |
| 9102 | Error assembling "{0}" {1} |
| 9103 | Error parsing "{0}" {1} |
| 9106 | Error creating log file: {0} |
| 9108 | Could not delete "{0}" from ODG "{1}": {2} |
| 9110 | Could not delete edge "{0}" to "{1}" from ODG "{2}": {3} |
| 9112 | Could not add edge "{0}" to "{1}" in ODG "{2}": {3} |
| 9114 | Invalid keyword "{0}" found, request rejected |
| 9115 | Required flag "{0}" was not specified |
| 9116 | One of the flags "{0}" must be specified |
| 9117 | Invalid edgetype "{0}" specified, request rejected |
| 9118 | Both keywords "{0}" and "{1}" are specified, but are mutually exclusive |
| 9122 | Exception taking snapshot: {0} |
| 9126 | Two arguments for the "{0}" flag must be specified |
| 9127 | One argument for the "{0}" flag must be specified |
| 9128 | Specified ODG "{0}" does not allow updates via API commands |
| 9129 | Specified ODG "{0}" does not exist |
| 9130 | Object "{0}" does not exist in ODG "{1}" |
| 9131 | ODG cycle detected, some objects in the chain: {0} |
| 9132 | Invalid edgetype "{0}" returned by dependency parser, verify configuration |
| 9135 | Leftover pages cannot be built - check for duplicates of: {0} |
| 9138 | Error writing "{0}" to repository in "{1}" {2} |
| 9140 | Request was purged before completion. |
| 9141 | {0} "{1}" does not exist |
| 9142 | {0} "{1}" is invalid, must be integer |
| 9143 | {0} "{1}" does not support enable/disable |
| 9150 | ODG Fatal Exception Processing Request |
| 9151 | Internal error {0} |