API for Dynamic Service Activator
This section contains information that developers need to create gateway clients and that administrators need to manage gateway clients and their interactions with the gateway.
Public SOAP Interfaces of Web Applications
When you have installed Dynamic Service Activator, you can access a Web Services Description Language (WSDL) file for the application. The WSDL file defines the SOAP properties that you or your customers can use to develop a gateway client. The URL for Dynamic Service Activator is:
http://<host>:<portNumber>/dsa/services/DynamicServiceActivation
?wsdl
- <host>—IP address or name of host that supports Dynamic Service Activator
- <portNumber>—Number of the TCP port
Methods for the Dynamic Service Activator SOAP Interface
This section describes the methods associated with Dynamic Service Activator, and provides information additional to that in the WSDL file (see Public SOAP Interfaces of Web Applications).
invokeScript
- Manages all operations involved with invoking scripts: retrieves requests to invoke scripts from the gateway client, authenticates the gateway client, verifies the arguments supplied by the gateway client, communicates with other SDX components, and returns values to the gateway client. For a complete description of Dynamic Service Activator's interactions with the gateway client and other components, see Dynamic Service Activator Operation.
- Arguments
- scriptName—String that contains the name of the script that the gateway client wants to invoke
- scriptArgs—String array of arguments that the gateway client passes to the script
- Expected output—Arbitrary string, depending on the particular script, contained in a SOAP response. For example, the string could be a indicator of success, an HTML page, or a complex data structure.
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_readSubscription
- Determines whether a subscriber accesses services through the SDX owner's network and obtains all that subscriber's subscriptions; returns the result in a one-dimensional array.
- Arguments
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI).
- Expected output—Multidimensional array of Attr objects that contain the subscriptions for the subscriber
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_readSubscription_retAttrSeq
- Determines whether a subscriber accesses services through the SDX owner's network and obtains all that subscriber's subscriptions; returns the result in a multi--dimensional array.
- Arguments
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI).
- Expected output—One-dimensional array of AttrSeq objects that contain the subscriptions for the subscriber
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_activateService
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI).
- subscriptionName—String that contains the name of the subscription
- sessionName—String that contains the name of the service session; default string is default
- activationAttributes—Array of one or more of the following attributes that can be specified for the subscription:
- sessionTimeout
- downstreamBandwidth
- upstreamBandwidth
- sessionTag
- subscriptionUsername
- subscriptionPassword
- substitutions
For information about these attributes, see Subscription Attributes.
- Expected output—None
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_deactivateService
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI).
- subscriptionName—String that contains the name of the subscription
- sessionName—String that contains the name of the service session; default string is default
- Expected output—None
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_modifyService
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI).
- subscriptionName—String that contains the name of the subscription
- sessionName—String that contains the name of the service session; default string is default
- optionalAttributes—Array of one or more of the following attributes that can be modified for the subscription:
For information about these attributes, see Subscription Attributes.
- Expected output—None
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_login
- Logs in subscribers
NOTE: This method supports only subscribers who are identified by their IP addresses. This method does not support subscribers who are identified by the names they use to log in or by their DNs.
- Arguments
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI).
- Expected output—Boolean operator that indicates success
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_logout
- Logs out subscribers. This method supports only subscribers who are identified by their IP addresses or the names they use to log in. This method does not support subscribers who are identified by their DNs.
- Arguments
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI).
- Expected output—None
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Format of the Subscriber's URI
Many of Dynamic Service Activator's methods require the argument subURI, the subscriber's uniform resource identifier (URI). This argument comprises two portions: the type of subscriber (subscriber-type) and a list of the subscriber's attributes <subscriber-comp>. The syntax for the subURI argument is:
<subscriber-type>:subscriber-comp [& subscriber-comp]*
The <subscriber-type> variable depends on the way the subscriber logs in. The syntax for the <subscriber-type> variable is:
address | dn | loginName| addressInterfaceName
- IP address—Subscriber's IP address
- dn—Subscriber's DN
- loginName—Name with which the subscriber logs in
- addressInterfaceName—IP address and name of interface on which subscriber logs in
The <subscriber-comp> variable has the format <type>=<value>.
The <type> variable has the syntax:
ipAddress |timestamp | dn | intfName |vrfName |login_name
- ipAddress—Subscriber's IP address; mandatory when <subscriberType> is ipAddress or addressInterfaceName
- timestamp—Time at which request was sent; optional when <subscriberType> is ipAddress
- dn—Subscriber's DN; mandatory for subscriberType dn
- intfName—Name of interface on which the subscriber logs in; optional when <subscriberType> is addressInterfaceName
- vrfName—Name of VRF associated with the subscriber; optional when <subscriberType> is addressInterfaceName
- login_name—Name with which the subscriber logs in; mandatory when <subscriberType> is loginName
The <value> variable uses the following syntax:
<operator> | <textString> | % <hexNumber>
; | / | ? | : | @ | & | = | + | $ | ,
Subscription Attributes
Some methods take attributes for subscriptions, as described below.
sessionTimeout
downstreamBandwidth
upstreamBandwidth
sessionTag
- Specifies the tag that the software uses to track a session for accounting purposes
- Value—Text string
- Example—News:Joe
subscriptionUsername
subscriptionPassword
substitutions
- Specifies the attributes and values that the method should substitute for existing settings
- Value—Array of strings; each array has the format <substutionType>=<substitutionValue>
- Example—Port=9999
SOAP Fault Codes for Dynamic Service Activator
When Dynamic Service Activator receives a SOAP request that it cannot handle, Dynamic Service Activator returns a SOAP fault message to the gateway client. This message contains a text string that specifies a SOAP fault code and a text string that provides additional information about the fault.
Dynamic Service Activator returns the following SOAP fault codes. If the SOAP fault code has the format client.<variables>, you must correct the gateway client. However, if the SOAP fault code has the format server.<variables>, you should record the error code and notify the gateway administrator.
Client.InvalidArguments
- One or more of the arguments for the script or method is an empty string or has a null value.
- Classification of call—Denied
- Action—Check that all arguments are correct.
Client.InvalidSubscriberFormat
- The SubURI argument, which the client passes to all methods except invokeScript, is invalid.
- Classification of call—Denied
- Action—Check that SubURI arguments are correct.
Server.AccessDenied
- SDX gateway does not recognize the client.
- Supplied name of method or script is incorrect.
- Number or value of the arguments supplied for the script or method is incorrect.
- Classification of call—Denied
- Action—Check that the values are correct. If they are, contact the gateway administrator.
Server.AccessControlMisconfiguration
- Gateway administrator did not configure Dynamic Service Activator correctly, in one of the following ways:
- The saeLocatorArg is not an integer.
- The number of arguments is less than the value of the saeLocatorArg parameter.
- The regular expressions are not correctly defined.
Server.Misconfiguration
- Gateway administrator did not configure the Web application to authenticate SOAP clients, and an unauthenticated client has passed a request to Dynamic Service Activator, which refuses unauthenticated requests.
- Classification of call—Failed
- Action—Contact the gateway administrator.
Server.SAEUnreachable
- Gateway client either cannot identify or cannot reach via CORBA the SAE server either on which the subscriber has logged in or on which the client wants to invoke a script.
- Classification of call—Failed
- Action—Contact the gateway administrator.
Server.SAE.UnkownSAEUser
- SAE on which Dynamic Service Activator tried to run a method or script cannot identify the subscriber. Dynamic Service Activator may have retained in its cache an SAE that is no longer current for the subscriber.
- Classification of call—Failed
- Action—Try this operation again. If it fails again, contact the gateway administrator.
Server.SAE.UserNotUniqueToSAE
- The subscriber is already active on the SAE on which Dynamic Service Activator tried to run a method or script. Dynamic Service Activator may have retained in its cache an SAE that is no longer current.
- Classification of call—Failed
- Action—Try this operation again. If it fails again, contact the gateway administrator.
Server.SAE.UnknownService
- SAE cannot identify the service that a subscription specifies.
- Classification of call—Failed
- Action—Check the service parameter for the following methods:
Server.SAE.UnknownSubscription
- SAE cannot identify the subscription that the subscriber wants to activate.
- Classification of call—Failed
- Action—Check the service parameter for the following methods:
Server.SAE.ServiceAuthenticationError
- The service that the subscriber wants to activate requires authentication.
- Classification of call—Failed
- Action—Check the activation attributes. If they are correct, contact the gateway administrator.
Server.SAE.UnknownServiceSession
- SAE cannot identify the service session that the subscriber wants to modify.
- Classification of call—Failed
- Action—Check the serviceId and sessionName parameters.
Server.SAE.LoginError
- Subscriber could not log in successfully.
- Failed
- Action—Check the subURI, username, and userPassword arguments.
Server.SAE.Exception
- SAE threw an exception after Dynamic Service Activator tried to run a method or script on the SAE.
- Classification of call—Failed
- Action—Contact the gateway administrator.
Server.SAE.Overload
- SAE threw an overload exception after Dynamic Service Activator tried to run a method or script on the SAE.
- Classification of call—Failed
- Action—Contact the gateway administrator.
Server.SAE.ScriptProcessorError
- SAE's script processor failed to invoke the script. This error could occur for many reasons, such as:
- Gateway administrator did not deploy the script on the SAE host.
- Gateway administrator did not configure the script processor correctly.