ActionEngine 22.12 ONVIF™ www.onvif.org December, 2022 2008-2022 ONVIF™ All rights reserved. Recipients of this document may copy, distribute, publish, or display this document so long as this copyright notice, license and disclaimer are retained with all copies of the document. No license is granted to modify this document. THIS DOCUMENT IS PROVIDED "AS IS," AND THE CORPORATION AND ITS MEMBERS AND THEIR AFFILIATES, MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THIS DOCUMENT ARE SUITABLE FOR ANY PURPOSE; OR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES, ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT, WHETHER OR NOT (1) THE CORPORATION, MEMBERS OR THEIR AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR (2) SUCH DAMAGES WERE REASONABLY FORESEEABLE, AND ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT.  THE FOREGOING DISCLAIMER AND LIMITATION ON LIABILITY DO NOT APPLY TO, INVALIDATE, OR LIMIT REPRESENTATIONS AND WARRANTIES MADE BY THE MEMBERS AND THEIR RESPECTIVE AFFILIATES TO THE CORPORATION AND OTHER MEMBERS IN CERTAIN WRITTEN POLICIES OF THE CORPORATION. 1.0 Feb-2012 Hasan T. Ozdemir First release. Change Request 1843 22.12 Dec-2022 Hans Busch Deprecate camera local recording action This document defines the web service interface for configuration of the Actions and Action Trigger conditions based on events. ONVIFTM Core Specification, Version 2.2, May, 2012 <> ONVIFTM Recording Control Service Specification, Version 2.2, May, 2012. <>

Action Trigger Condition. Topic and message content filter based condition Action Executed when one of its conditions (Action Trigger) is satisfied

FTP File Transfer Protocol E-Mail Electronic Mail SMTP Simple Mail Transfer Protocol POP Post Office Protocol SMS Short Message Service

Table 1 lists the prefix and namespaces used in this specification. Listed prefixes are not part of the standard and an implementation can use any prefix. Prefix Namespace URI Description tt http://www.onvif.org/ver10/schema XML schema descriptions in this specification. tae http://www.onvif.org/ver10/actionengine/wsdl The namespace for the WSDL action engine service. ter http://www.onvif.org/ver10/error The namespace for ONVIF defined faults. tns1 http://www.onvif.org/ver10/topics The namespace for the ONVIF topic namespace This specification references to the following namespaces (listed in Table 2) by specified prefix. Prefix Namespace URI Description soapenv http://www.w3.org/2003/05/soap-envelope Envelope namespace as defined by SOAP 1.2 [SOAP 1.2, Part 1] xs http://www.w3.org/2001/XMLSchema Instance namespace as defined by XS [XML-Schema, Part1] and [XML-Schema, Part 2]

This document describes Action Engine web service depicted also in video analytics architecture (Figure 6) in [Video Analytics Service Specification]. The Action Engine service enables new extensible device capabilities by providing further integration opportunities with other networked devices through actions that are triggered by events.

Action Engine service interface allows service requester to list available action types (defined in action description language), creates new actions, modify the action configurations, and delete actions.

Action Engine interface also allows service requester to define the action triggers that are defined based on Topic expression (Section Topic Filter in [Core Specification]) and Message Content expression (Section Message Content Filter in [Core Specification]). Service requester can list, create, modify, and delete the action triggers. Action Engine service provider passes the triggering event information to triggered action instances.

The configuration of an action contains the action name and the other Action type specific parameter configurations. The Parameters element of the Action element contains the configurations of action parameters. Each Parameter is defined by either a SimpleItem or an ElementItem data type. The Name attribute of each parameter shall be unique within the parameter list. The Value attribute of SimpleItem contains the parameter configuration. The child element of an ElementItem contains the configured value of an ElementItem. It is RECOMMENDED to represent as many configuration parameters as possible by SimpleItems.

The description of an Action contains the action type name (Name) and the type information of all parameters belonging to the defined Action type. The parameters of a certain Action Type are listed below the ParameterDescription element. All parameters are either Simple or ElementItems and can be described by either a SimpleItemDescription or an ElementItemDescription. Both ItemDescriptions contain a Name attribute to identify the parameter and a Type attribute to reference a specific XML schema type. The Type attribute of the SimpleItemDescription shall reference to XML schema simple type definition. The Type attribute of the ElementItemDescription shall reference a global element declaration of an XML schema. Section demonstrates the usage of the Action Description Language. The following definitions are included for convenience: ]]>

If the device supports an Action Engine service as defined by ONVIF, then it shall implement the following operations to manage actions. The Create/Delete/Modify operations are atomic, meaning that either all modifications can be processed or the complete operation shall fail.

The service provider returns the supported action types. The response returns a list of Action Descriptions according to the Action Description Language described in Section . The response also contains a list of URLs that provide the location of the schema files. These schema files describe the types and elements used in the Action Descriptions. If action descriptions reference types or elements of the ONVIF schema file, the ONVIF schema file shall be explicitly listed. request This is an empty message. response SupportedActions [tt:SupportedActions] The response contains the supported actions. faults There are no operation specific faults. access class READ_SYSTEM

The get actions operation retrieves currently installed Actions. request This is an empty message. response Action - optional, unbounded [tt:Action] The response is a list of installed actions for the specified configuration. faults There are no operation specific faults. access class READ_SYSTEM

The create action operation adds actions to configuration. The create action operation is atomic. If a service provider can not create all of requested actions, then, the service provider responds with a fault message. request Action - unbounded [tt:ActionConfiguration] The request message specifies list of Actions to be added. response Action - optional, unbounded [tt:Action] The response is a list of created actions. faults env:Sender - ter:InvalidArgVal - ter:InvalidAction The requested actions configuration is not valid. env:Sender - ter:InvalidArgVal - ter:UknownAction The requested action type is not known. enc:Receiver - ter:Action - ter:TooManyActions There is not enough space to add actions. access class WRITE_SYSTEM

The modify action operation modifies action configurations. The modify action operation is atomic. If a service provider can not modify all of requested action configurations, then, the service provider responds with a fault message. request Action - unbounded [tt:Action] The request message specifies list of Actions to be modified. response This is an empty message. faults env:Sender - ter:InvalidArgVal - ter:InvalidAction The requested action configuration is not valid. env:Sender - ter:InvalidArgs - ter:ActionNotExist The actions do not exist. access class WRITE_SYSTEM All action parameters, except the action type, can be modified. The service provider shall return InvalidAction error if the request attempts to change the action type with modify action request.

The delete operation deletes actions. The delete action operation is atomic. If a service provider can not delete all of requested actions, then, the service provider responds with a fault message. request Token - unbounded [xs:ReferenceToken] The request message specifies list of Actions to be removed. response This is an empty message. faults env:Sender - ter:InvalidArgs - ter:ActionNotExist The actions do not exist. env:Receiver - ter:Action - ter:ConfigurationConflict The service cannot delete the actions without creating a conflicting configuration. access class WRITE_SYSTEM

The get capabilities operation returns the Action Engine capabilities. request This is an empty message. response Capabilities [tt:ActionEngineCapabilities] The capability response message contains Action Engine capabilities information. faults There are no operation specific faults. access class PRE_AUTH The capabilities data structure indicates the maximum number of action and action trigger instances.

Returns configured action triggers. request This is an empty message. response ActionTrigger - optional, unbounded [tt:ActionTrigger] The request message specifies list of action triggers. faults There are no operation specific faults. access class READ_SYSTEM

Creates action triggers. The create action triggers operation is atomic. If a service provider can not create all of requested action triggers, then, the service provider responds with a fault message. request ActionTrigger - unbounded [tt:ActionTriggerConfiguration] The request message specifies list of action triggers to be created. response ActionTrigger - optional, unbounded [tt:ActionTrigger] The request message specifies list of action triggers. faults env:Sender - ter:InvalidArgVal - ter:InvalidActionTrigger The requested action trigger configuration is not valid. env:Receiver - ter:Action - ter:TooManyActionTriggers There is not enough space to add action triggers. access class WRITE_SYSTEM

Modifies existing action triggers. The modify action triggers operation is atomic. If a service provider can not modify all of requested action trigger configurations, then, the service provider responds with a fault message. request ActionTrigger - unbounded [tt:ActionTrigger] The request message specifies list of action triggers to be modified. response This is an empty message. faults env:Sender - ter:InvalidArgVal - ter:InvalidActionTrigger The requested action trigger configuration is not valid. env:Sender - ter:InvalidArgs - ter:ActionTriggerNotExist The action triggers do not exist. access class WRITE_SYSTEM

Deletes action triggers. The delete action triggers operation is atomic. If a service provider can not delete all of requested action triggers, then, the service provider responds with a fault message. request Token - unbounded [tt:ReferenceToken] The request message specifies list of action triggers to be removed. response This is an empty message. faults env:Sender - ter:InvalidArgs - ter:ActionTriggerNotExist The action triggers do not exist. access class WRITE_SYSTEM

The command action executes one or more ONVIF commands on the device itself or on a remote device. This mechanism is applicable to a wide range of ONVIF commands. <tt:ActionDescription Name="tt:CommandAction"> <tt:ParameterDescription> <tt:SimpleItemDescription Name="XAddr" Type="xs:anyURI"/> <tt:SimpleItemDescription Name="Operation" Type="xs:QName"/> <tt:ElementItemDescription Name="Parameters" Type="tt:AnyHolder"/> </tt:ParameterDescription> </tt:ActionDescription> Parameters Description Xaddr Endpoint where the command shall be executed. Use localhost for local commands instead to avoid that device IP address changes break the commands. Operation Operation name including namespace Parameters Input parameter of the operation as defined in the corresponding ONVIF WSDL file.

E-mail action definition allows application to send an e-mail to the configured addresses. The e-mail content is provided during the execution. Parameters Description EMailServerConfiguration Contains Email Server configuration SMTP Configuration SMTP Server IP address and port number POP Configuration POP Server IP address and port number Authentication Configuration Configure username and password Receivers Contains list of receivers (TO and CC fields) Sender (From) Sender information Subject E-Mail subject Line configuration Body E-Mail body text configuration Attachment E-Mail Attachment file name configuration File Name Attachment file name File Name Suffix Attachment file name suffix configuration Media Reference Media Profile Token

HTTP POST action definition allows application to send data to the configured address via HTTP POST mechanism. The content is provided during the execution. ]]> Parameters Description Destinations Contains HTTP server configurations Server Address Server IP address and port number Authentication Server Authentication configuration (username, password, authentication mechanism) URI Request-Uri Protocol Select HTTP or HTTPS POST Content POST content configuration for form data, triggering event data, and media Media Reference Media Profile Token

FTP action definition allows application to send data to the configured address via FTP mechanism. The content is provided during the execution. Parameters Description Destinations Server Address Server IP and Port number configuration Upload Path Upload path on FTP server Authentication Authentication configuration FTP Content FTP Content Configuration Includes configurations for the upload of sequence of images and upload of a file from local storage Media Reference Media Profile Token

SMS action definition allows application to send data to the configured address via SMS Text Messaging mechanism. The content is provided during the execution. ]]> Parameters Description SMSProvider SMS Provider Information SMSSenderInfo SMS Sender Information Destination Destinations that will receive the message Message Text Message

Note, that this interface has been deprecated since the same functionality can be configured directly via the recording control service. Camera Local Recording Action definition allows application to initiate recording of data to the camera local storage. The content is provided during the execution. ]]> Parameters Description Recording configuration Local recording configuration Pre recording duration Recording before the triggering event Post recording duration Recording after alarm recording duration Record duration Record duration Recording frame rate Recording frame rate Audio Recording on/off Whether Audio recording on/off

The capabilities reflect optional functions and functionality of a service. The following capabilities are available: MaximumActions: The maximum number of actions that the service provider can concurrently support. MaximumTriggers: The maximum number of trigger configurations that the service provider can concurrently support.

The action engine events allow controlling of action execution as well as building of action chains. The action service shall dispatch events through the event service.

The device shall be capable of generating the following event whenever an action has been completed. This event is triggered whenever an action completes without a fault message. When an event is generated due to execution of CommandAction, the Data element of event message can contain the typed information of the request and response message payloads of corresponding ONVIF message exchange. Topic: tns1:ActionEngine/Completed <tt:MessageDescription IsProperty="false"> <tt:Source> <tt:SimpleItemDescription Name="Token" Type="tt:ReferenceToken"/> <tt:SimpleItemDescription Name="ActionName" Type="xs:string"/> </tt:Source> <tt:Data> <tt:ElementItemDescription Name="RequestResponse" Type="tt:ActionEngineEventPayload"/> </tt:Data> </tt:MessageDescription>

The device shall be capable of generating the following event whenever an action has been completed with an error. This event is triggered whenever an action completes with a fault message or the action could not be executed because of the other error. The response contains the fault codes including any sub codes. Topic: tns1:ActionEngine/Failed <tt:MessageDescription IsProperty="false"> <tt:Source> <tt:SimpleItemDescription Name="Token" Type="tt:ReferenceToken"/> <tt:SimpleItemDescription Name="ActionName" Type="xs:string"/> </tt:Source> <tt:Data> <tt:ElementItemDescription Name="RequestResponse" Type="tt:ActionEngineEventPayload"/> </tt:Data> </tt:MessageDescription>

Starting and stopping of recording job on Recording Control Service by using CommandAction definition is illustrated in the following. Start a recording on the same device when a relay is switched on. <tae:Action Token=”453638”> <tae:Configuration Name=”StartRecording” Type=”tae:CommandAction”> <tt:Parameters> <tt:SimpleItem Name=”XAddr” Value=”http://127.0.0.1/onvif/device_service”/> <tt:SimpleItem Name=”Operation” Value=”tt:SetRecordingJobMode”/> <tt:ElementItem Name=”Parameters”> <tt:JobToken>123</tt:JobToken> <tt:Mode>Active</tt:Mode> </tt:ElementItem> </tt:Parameters> </tae:Configuration> </tae:Action> Stop the recording one minute after the relay is switched off. <tae:Action Token=”5674749”> <tae:Configuration Name=”StopRecording” Type=”tae:CommandAction”> <tt:Parameters> <tt:SimpleItem Name=”XAddr” Value=”http://127.0.0.1/onvif/device_service”/> <tt:SimpleItem Name=”Operation” Value=”tt:SetRecordingJobMode”/> <tt:ElementItem Name=”Parameters”> <tt:JobToken>123</tt:JobToken> <tt:Mode>Idle</tt:Mode> </tt:ElementItem> </tt:Parameters> </tae:Configuration> </tae:Action>

The following demonstrates the E-Mail action configuration information. 172.34.123.65 162.34.123.56 sg1@hq.co sg2@hq.co sgm@hq.co NVT@123.23.23.22 EVT_ dateTime 4757585 ]]>

The following demonstrates the configuration for HTTP POST action. The configuration utilizes the Media Profile Reference to indicate the media source. 192.134.123.214 6565746 ]]>

An example configuration for sending images (from Media Profile) into a directory (Destinations/UploadPath) in FTP server (Destinations) for 15 minutes (FtpContent/HowLong) with 10 seconds snapshots (FtpContent/SampleInterval) with the configured file names (FtpContent/FileName). 132.34.13.64 /home/cam2 P0Y0M0DT0H15M P0Y0M0DT0H0M10S 5657959 ]]>

For example, GetActionsResponse message contains installed Action information as; .. …. …. ]]> ..