Transcription
ONVIF TM–1–Action Engine Service Spec-v1.0ONVIFTMAction Engine Service SpecificationVersion 1.0May, 2012
ONVIF TM–2–Action Engine Service Spec-v1.0 2008-2012 by ONVIF: Open Network Video Interface Forum. All rights reserved.Recipients of this document may copy, distribute, publish, or display this document so long as thiscopyright notice, license and disclaimer are retained with all copies of the document. No license is grantedto modify this document.THIS DOCUMENT IS PROVIDED "AS IS," AND THE CORPORATION AND ITS MEMBERS AND THEIRAFFILIATES, MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDINGBUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULARPURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THIS DOCUMENT ARESUITABLE FOR ANY PURPOSE; OR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOTINFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FORANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES,ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT, WHETHEROR NOT (1) THE CORPORATION, MEMBERS OR THEIR AFFILIATES HAVE BEEN ADVISED OF THEPOSSIBILITY OF SUCH DAMAGES, OR (2) SUCH DAMAGES WERE REASONABLY FORESEEABLE,AND ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT. THEFOREGOING DISCLAIMER AND LIMITATION ON LIABILITY DO NOT APPLY TO, INVALIDATE, ORLIMIT REPRESENTATIONS AND WARRANTIES MADE BY THE MEMBERS AND THEIR RESPECTIVEAFFILIATES TO THE CORPORATION AND OTHER MEMBERS IN CERTAIN WRITTEN POLICIES OFTHE CORPORATION.
ONVIF TM–3–Action Engine Service Spec-v1.0CONTENTS1Scope. 52Normative references. 53Terms and Definitions . 543.1 Definitions .3.2 Abbreviations .3.3 Namespaces.Overview .5Service . 95.15.25.35557Action representation . 9Action description language . 9Operations on actions . 95.3.1 GetSupportedActions . 95.3.2 GetActions .105.3.3 CreateActions .105.3.4 ModifyActions .115.3.5 DeleteActions.115.3.6 GetServiceCapabilities .125.3.7 GetActionTriggers .135.3.8 CreateActionTriggers .135.3.9 ModifyActionTriggers.135.3.10 DeleteActionTriggers.145.4 Standard actions.155.4.1 CommandAction.155.4.2 E-Mail Action .165.4.3 HTTP POST Action .175.4.4 FTP Action .185.4.5 SMS Action .195.4.6 Camera Local Recording Action.205.5 Capabilities .215.6 Events .215.6.1 Action completed .215.6.2 Action failed .215.7 Service-specific data types .235.7.1 ActionConfiguration .235.7.2 Action .235.7.3 ActionTriggerConfiguration .245.7.4 ActionTrigger .245.7.5 ActionEngineCapabilities .255.7.5.1 ActionTypeLimits .255.7.6 SupportedActions .255.7.7 ActionEngineEventPayload.275.8 Service-specific fault codes.28Annex A.29
ONVIF TMA.1A.2A.3A.4A.5Annex B.–4–Action Engine Service Spec-v1.0Example: Command Action configuration.29Example: E-Mail Action configuration .30Example: HTTP POST Action configuration .31Example: FTP Action configuration.32Example: GetActions Response .33Revision History .34
ONVIF TM1–5–Action Engine Service Spec-v1.0ScopeThis document defines the web service interface for configuration of the Actions and ActionTrigger conditions based on events.2Normative referencesONVIF TM Core Specification, Version 2.2, May, 2012 cation-v220.pdf ONVIFTM Recording Control Service Specification, Version 2.2, May, 2012. Control-Service-Spec-v220.pdf 3Terms and Definitions3.1DefinitionsAction TriggerAction3.2AbbreviationsFile Transfer ProtocolElectronic MailSimple Mail Transfer ProtocolPost Office ProtocolShort Message ServiceFTPE-MailSMTPPOPSMS3.3Condition. Topic and message content filter based conditionExecuted when one of its conditions (Action Trigger) is satisfiedNamespacesTable 1 lists the prefix and namespaces used in this specification. Listed prefixes are not part ofthe standard and an implementation can use any prefix.Table 1: Namespaces used in this specificationPrefixNamespace f.org/ver10/topicsXML schema descriptions in thisspecification.The namespace for the WSDL actionengine service.The namespace for ONVIF definedfaults.The namespace for the ONVIF topicnamespaceThis specification references to the following namespaces (listed in Table 2) by specified prefix.
ONVIF TM–6–Action Engine Service Spec-v1.0Table 2: Referenced namespacesPrefixNamespace pe namespace as defined bySOAP 1.2 [SOAP 1.2, Part 1]Instance namespace as defined by XS[XML-Schema, Part1] and [XMLSchema, Part 2]
ONVIF TM4–7–Action Engine Service Spec-v1.0OverviewThis document describes Action Engine web service depicted also in video analytics architecture(Figure 6) in [Video Analytics Service Specification]. The Action Engine service enables newextensible device capabilities by providing further integration opportunities with other networkeddevices through actions that are triggered by events.ActionAction cfgAction EngineEventEvent EngineEvent cfgEvent(s)Rule cfgRule EngineScene descriptionAnalytics cfgVideo Analytics EngineImageFigure 1 Video Analytics ArchitectureAction Engine service interface allows service requester to list available action types (defined inaction description language), creates new actions, modify the action configurations, and nseDeleteActionsDeleteActionsResponseFigure 2 Action creation and configuration sequence
ONVIF TM–8–Action Engine Service Spec-v1.0Action Engine interface also allows service requester to define the action triggers that are definedbased on Topic expression (Section Topic Filter in [Core Specification]) and Message Contentexpression (Section Message Content Filter in [Core Specification]). Service requester can list,create, modify, and delete the action triggers. Action Engine service provider passes thetriggering event information to triggered action instances.
ONVIF TM5–9–Action Engine Service Spec-v1.0Service5.1Action representationThe configuration of an action contains the action name and the other Action type specificparameter configurations. The Parameters element of the Action element contains theconfigurations of action parameters. Each Parameter is defined by either a SimpleItem or anElementItem data type. The Name attribute of each parameter shall be unique within theparameter list. The Value attribute of SimpleItem contains the parameter configuration. The childelement of an ElementItem contains the configured value of an ElementItem. It isRECOMMENDED to represent as many configuration parameters as possible by SimpleItems.5.2Action description languageThe description of an Action contains the action type name (Name) and the type information of allparameters belonging to the defined Action type. The parameters of a certain Action Type arelisted below the ParameterDescription element. All parameters are either Simple or ElementItemsand can be described by either a SimpleItemDescription or an ElementItemDescription. BothItemDescriptions contain a Name attribute to identify the parameter and a Type attribute toreference a specific XML schema type. The Type attribute of the SimpleItemDescription shallreference to XML schema simple type definition. The Type attribute of theElementItemDescription shall reference a global element declaration of an XML schema.Section 5.4 demonstrates the usage of the Action Description Language. The following definitionsare included for convenience: xs:element name "ActionDescription" type "tt:ActionConfigDescription"/ xs:complexType name "ActionConfigDescription" xs:sequence xs:element name "ParameterDescription"type "tt:ItemListDescription"/ /xs:sequence xs:attribute name "Name" type "xs:QName" use "required"/ xs:anyAttribute processContents "lax"/ /xs:complexType 5.3Operations on actionsIf the device supports an Action Engine service as defined by ONVIF, then it shall implement thefollowing 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.5.3.1GetSupportedActionsThe service provider returns the supported action types. The response returns a list of ActionDescriptions according to the Action Description Language described in Section 5.2. Theresponse also contains a list of URLs that provide the location of the schema files. These schemafiles describe the types and elements used in the Action Descriptions. If action descriptionsreference types or elements of the ONVIF schema file, the ONVIF schema file shall be explicitlylisted.
ONVIF TM– 10 –Action Engine Service Spec-v1.0Table 3: GetSupportedActions commandAccess Class:READ SYSTEMGetSupportedActionsMessage esponseDescriptionThis is an empty message.The response contains the supported actions.tt:SupportedActions SupportedActions [1][1]Fault codesDescriptionThere are no operation specific faults.5.3.2GetActionsThe get actions operation retrieves currently installed Actions.Table 4: GetActions commandAccess Class:READ SYSTEMGetActionsMessage nameDescriptionGetActionsRequestThis is an empty message.GetActionsResponseThe response is a list of installed actions for the specified configuration.tt:Action Action [0][unbounded]Fault codesDescriptionThere are no operation specific faults.5.3.3CreateActionsThe 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 respondswith a fault message.Table 5: CreateActions commandAccess Class:WRITE SYSTEMCreateActionsMessage nameCreateActionsRequestDescriptionThe request message specifies list of Actions to be added.tt:ActionConfiguration Action [1][unbounded]CreateActionsResponseThe response is a list of created actions.tt:Action Action [0][unbounded].Fault codesDescriptionenv:Senderter:InvalidArgValThe requested actions configuration is not valid.
ONVIF TM– 11 ons5.3.4Action Engine Service Spec-v1.0The requested action type is not known.There is not enough space to add actions.ModifyActionsThe 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 serviceprovider responds with a fault message.Table 6: ModifyActions commandAccess Class:WRITE SYSTEMModifyActionsMessage nameDescriptionModifyActionsRequestThe request message specifies list of Actions to be modified.ModifyActionsResponsett:Action Action[1][unbounded]This is an empty message.Fault istThe requested action configuration is not valid.The actions do not exist.All action parameters, except the action type, can be modified. The service provider shall returnInvalidAction error if the request attempts to change the action type with modify action request.5.3.5DeleteActionsThe delete operation deletes actions. The delete action operation is atomic. If a service providercan not delete all of requested actions, then, the service provider responds with a fault message.Table 7: DeleteActions commandAccess Class:WRITE SYSTEMDeleteActionsMessage nameDescriptionDeleteActionsRequestThe request message specifies list of Actions to be removed.DeleteActionsResponsexs:ReferenceToken Token[1][unbounded]The response is an empty message.Fault codesDescription
ONVIF TM– 12 tion Engine Service Spec-v1.0The actions do not exist.The service cannot delete the actions without creating a conflictingconfiguration.GetServiceCapabilitiesThe get capabilities operation returns the Action Engine capabilities.Table 8: Get Service Capabilities commandAccess Class:PRE AUTHGetServiceCapabilitiesMessage nameDescriptionGetServiceCapabilitiesRequestThe request is an empty message.GetServiceCapabilitiesResponseThe capability response message contains Action Enginecapabilities information.tt:ActionEngineCapabilities Capabilities [1][1]Fault codesDescriptionThere are no operation specific faults.The capabilities data structure indicates the maximum number of action and action triggerinstances (See Section 5.7.5).
ONVIF TM5.3.7– 13 –Action Engine Service Spec-v1.0GetActionTriggersReturns configured action triggers.Table 9: GetActionTriggers commandAccess Class:READ SYSTEMGetActionTriggersMessage nameDescriptionGetActionTriggersRequestThis is an empty message.GetActionTriggersResponseThe request message specifies list of action triggers.Fault codesDescriptiontt:ActionTrigger ActionTrigger[0][unbounded]There are no operation specific faults.5.3.8CreateActionTriggersCreates action triggers. The create action triggers operation is atomic. If a service provider cannot create all of requested action triggers, then, the service provider responds with a faultmessage.Table 10: CreateActionTriggers commandAccess Class:WRITE SYSTEMCreateActionTriggersMessage nameDescriptionCreateActionTriggersRequestThe request message specifies list of action triggers to be erConfiguration ActionTrigger [1][unbounded]The request message specifies list of action triggers.tt:ActionTrigger ActionTrigger[0][unbounded]Fault ActionTriggersThe requested action trigger configuration is not valid.5.3.9There is not enough space to add action triggers.ModifyActionTriggersModifies existing action triggers. The modify action triggers operation is atomic. If a serviceprovider can not modify all of requested action trigger configurations, then, the service providerresponds with a fault message.
ONVIF TM– 14 –Action Engine Service Spec-v1.0Table 11: ModifyActionTriggers commandAccess Class:WRITE SYSTEMModifyActionTriggersMessage nameDescriptionModifyActionTriggersRequestThe request message specifies list of action triggers to be ger ActionTrigger[1][unbounded]This is an empty message.Fault onTriggerNotExistThe requested action trigger configuration is not valid.5.3.10The action triggers do not exist.DeleteActionTriggersDeletes action triggers. The delete action triggers operation is atomic. If a service provider cannot delete all of requested action triggers, then, the service provider responds with a faultmessage.Table 12: DeleteActionTriggers commandAccess Class:WRITE SYSTEMDeleteActionTriggersMessage nameDescriptionDeleteActionTriggersRequestThe request message specifies list of action triggers to be ken Token[1][unbounded]This is an empty message.Fault nTriggerNotExistThe action triggers do not exist.
ONVIF TM5.4– 15 –Action Engine Service Spec-v1.0Standard actions5.4.1 CommandActionThe command action executes one or more ONVIF commands on the device itself or on a remotedevice. 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 The Action has the following configuration parameters;ParametersDescriptionXaddrEndpoint where the command shall be executed.Use localhost for local commands instead to avoidthat device IP address changes break thecommands.OperationOperation name including namespaceParametersInput parameter of the operation as defined in thecorresponding ONVIF WSDL file.
ONVIF TM5.4.2– 16 –Action Engine Service Spec-v1.0E-Mail ActionE-mail action definition allows application to send an e-mail to the configured addresses. The email content is provided during the execution. tt:ActionDescription Name "tt:EMailAction" tt:ParameterDescription tt:ElementItemDescription Name "Destinations"Type "tae:EMailServerConfiguration"/ tt:ElementItemDescription Name "Receivers" Type "tae:EMailReceiverConfiguration"/ tt:SimpleItemDescription Name "Sender"Type "xs:string"/ tt:SimpleItemDescription Name "Subject"Type "xs:string"/ tt:ElementItemDescription Name "Body"Type "tae:EMailBodyTextConfiguration"/ tt:ElementItemDescription Name "Attachment"Type "tae:EMailAttachmentConfiguration” / tt:ElementItemDescription Name "MediaReference" Type "tt:MediaSource”/ /tt:ParameterDescription /tt:ActionDescription The Action has the following configuration rationContains Email Server configurationSMTP ConfigurationSMTP Server IP address and port numberPOP ConfigurationPOP Server IP address and port numberAuthentication ConfigurationConfigure username and passwordReceiversContains list of receivers (TO and CC fields)Sender (From)Sender informationSubjectE-Mail subject Line configurationBodyE-Mail body text configurationAttachmentE-Mail Attachment file name configurationFile NameAttachment file nameFile Name SuffixAttachment file name suffix configurationMedia ReferenceMedia Profile Token
ONVIF TM5.4.3– 17 –Action Engine Service Spec-v1.0HTTP POST ActionHTTP POST action definition allows application to send data to the configured address via HTTPPOST mechanism. The content is provided during the execution. tt:ActionDescription Name "tt:HttpPOSTAction" tt:ParameterDescription tt:ElementItemDescription Name "Destinations" Type "tae:HttpHostConfigurations"/ tt:ElementItemDescription Name "POSTContent" Type "tae:PostContentConfiguration"/ /tt:ParameterDescription /tt:ActionDescription The Action has the following configuration ns HTTP server configurationsServer AddressServer IP address and port numberAuthenticationServer Authentication configurationauthentication mechanism)URIRequest-UriProtocolSelect HTTP or HTTPSPOST ContentMedia Reference(username,password,POST content configuration for form data, triggering event data,and mediaMedia Profile Token
ONVIF TM5.4.4– 18 –Action Engine Service Spec-v1.0FTP ActionFTP action definition allows application to send data to the configured address via FTPmechanism. The content is provided during the execution. tt:ActionDescription Name "tt:FtpAction" tt:ParameterDescription tt:ElementItemDescription Name "Destinations" Type "tae:FtpHostConfigurations"/ tt:ElementItemDescription Name "FtpContent" Type "tae:FtpContentConfiguration”/ tt:ElementItemDescription Name "MediaReference" Type "tt:MediaSource”/ /tt:ParameterDescription /tt:ActionDescription The Action has the following configuration parameters;ParametersDescriptionDestinationsServer AddressServer IP and Port number configurationUpload PathUpload path on FTP serverAuthenticationAuthentication configurationFTP ContentFTP Content ConfigurationIncludes configurations for the upload ofsequence of images and upload of a file fromlocal storageMedia ReferenceMedia Profile Token
ONVIF TM5.4.5– 19 –Action Engine Service Spec-v1.0SMS ActionSMS action definition allows application to send data to the configured address via SMS TextMessaging mechanism. The content is provided during the execution. tt:ActionDescription Name "tt:SMSNotificationAction" tt:ParameterDescription tt:ElementItemDescription Name "SMSProvider"Type "tae:SMSProviderConfiguration"/ tt:ElementItemDescription Name "SMSSenderInfo"Type "tae:SMSSenderConfiguration"/ tt:SimpleItemDescription Name "Destination" Type "xs:string"/ tt:SimpleItemDescription Name "Message" Type "tae:SMSMessage"/ /tt:ParameterDescription /tt:ActionDescription The Action configuration contains the following configuration parameters;ParametersDescriptionSMSProviderSMS Provider InformationSMSSenderInfoSMS Sender InformationDestinationDestinations that will receive the messageMessageText Message
ONVIF TM5.4.6– 20 –Action Engine Service Spec-v1.0Camera Local Recording ActionCamera Local Recording Action definition allows application to initiate recording ofdata to the camera local storage. The content is provided during the execution. tt:ActionDescription Name "tt:RecordingAction" tt:ParameterDescription tt:ElementItemDescription Name "RecordingConfiguration"Type "tae:RecordingActionConfiguration"/ /tt:ParameterDescription /tt:ActionDescription The Action configuration contains the following configuration parameters;ParametersDescriptionRecording configurationLocal recording configurationPre recording durationRecording before the triggering eventPost recording durationRecording after alarm recording durationRecord durationRecord durationRecording frame rateRecording frame rateAudio Recording on/offWhether Audio recording on/off
ONVIF TM5.5– 21 –Action Engine Service Spec-v1.0CapabilitiesThe capabilities reflect optional functions and functionality of a service. The following capabilitiesare available:MaximumActions:support.The maximum number of actions that the service provider can concurrentlyMaximumTriggers: The maximum number of trigger configurations that the service provider canconcurrently support.5.6EventsThe 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.5.6.1 Action completedThe device shall be capable of generating the following event whenever an action has beencompleted. This event is triggered whenever an action completes without a fault message. Whenan event is generated due to execution of CommandAction, the Data element of event messagecan contain the typed information of the request and response message payloads ofcorresponding 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 5.6.2 Action failedThe device shall be capable of generating the following event whenever an action has beencompleted with an error.This event is triggered whenever an action completes with a fault message or the action could notbe executed because of the other error. The response contains the fault codes including any subcodes.Topic: tns1:ActionEngine/Failed tt:MessageDescription IsProperty "false" tt:Source tt:SimpleItemDescription Name "Token" Type "tt:ReferenceToken"/
ONVIF TM– 22 –Action Engine Service Spec-v1.0 tt:SimpleItemDescription Name "ActionName" Type "xs:string"/ /tt:Source tt:Data tt:ElementItemDescription Name "RequestResponse"Type "tt:ActionEngineEventPayload"/ /tt:Data /tt:MessageDescription
ONVIF TM– 23 –Action Engine Service Spec-v1.05.7 Service-specific data types5.7.1ActionConfigurationAction Configuration data type contains the configuration settings of action configurationparameters, service requester given action Name, and service provider supported action typevalue. xs:complexType name "ActionConfiguration"/ xs:attribute name "Name" type "xs:string" use "required"/ xs:attribute name "Type" type "xs:QName" use "required"/ xs:element name "Parameters" type "tt:ItemList"/ /xs:complexType NameUser given name. TypeDenotes the action type. ParametersAction configuration parameter settings.5.7.2ActionAction data type contains the configuration settings of one action instance and service providerassigned unique identifier for this action configuration. xs:complexType name "Action"/ xs:attribute name "Token" type "tt:ReferenceToken" use "required"/ xs:element name "Configuration" type "tae:ActionConfiguration"/ /xs:complexType TokenUnique Action identifier that service implementation assigned to the action configuration. ConfigurationAction configuration contains action type, user given action name, and configurationparameter settings.
ONVIF TM5.7.3– 24 –Action Engine Service Spec-v1.0ActionTriggerConfigurationAction Trigger configuration data type contains mandatory Topic Expression (Section Topic Filterin [Core Specification]), optional Message content expression (Section Message Content Filter in[Core Specification]), and set of actions to be triggered. xs:complexType name "ActionTriggerConfiguration"/ xs:element name "TopicExpression" type "wsnt:TopicExpressionType"/ xs:elementname "ContentExpression"type "wsnt:QueryExpressionType"minOccurs "0"/ xs:element name "ActionToken" type "tt:ReferenceToken" minOccurs "0"maxOccurs "unbounded"/ /xs:complexType TopicExpresionTopic expression, for example, to trigger only for relays. Trigger based on event topic. ContentExpressionContent expression, for example, to trigger only when the relay value is “On”. Triggerbased on content data in event. ActionTok
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 . 5.2. 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 .
