This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?


class EnsLib.ITK.Framework.Service.SOAPServiceBase extends EnsLib.SOAP.Service, EnsLib.ITK.Framework.SOAPCommon

SOAP Service - Acts both as Business and Web Service.

Property Inventory

Method Inventory


parameter ADAPTER = EnsLib.SOAP.InboundAdapter;
Inherited description: Name of the adapter class - override this to "" if you want to use only the regular SOAP mechanism and not the custom-port InboundAdapter.
Use xsi:type attribute for literal types.
The SECURITYIN parameter controls the treatment of a WS-Security header in the input SOAP message. The possible value of SECURITYIN are ALLOW, IGNORE and REQUIRE.
- The default value of IGNORE will ignore any WS-Security headers in the input except for the UsernameToken which can always be used to login the user.
- The value of ALLOW will cause the WS-Security header to be verified on input.
- The value of REQUIRE will require the presence of the WS-Secufrity header and verify the header on input.

Note that if validation of the Security header is enabled (ALLOW or REQUIRE), then a CA file, named cache.cer, containing the trusted root X509 certificates should be put in the Cache Mgr directory if signature verification or decryption is to be performed. An optional Certificate Revocagtion List (cache.crl) may also be put in the Cache Mgr directory.
This is the name of the Service
parameter SETTINGS = EndpointURL,MaxFileSizeMB,FaultVocabulary,PromoteITKExtensions,WSSecurityPassword,SignedHeaders,SOAPBodyEncrypted,TargetConfigName,SynchronousTimeout;
Inherited description: Can't do grace period without an OnTask loop
parameter SOAPHEADERS = Header:%SOAP.Header,Security:%SOAP.Security.Header;
A list of supported SOAP headers is specified as a comma separated list of input header specifications. Each specification is of the form "headerName:headerClass" where headerName is the element name of the supported header and headerClass is the %SOAP.Header subclass that corresponds to that header. This list defines all headers supported in the SOAP request.


property AlertError as %Boolean [ InitialExpression = 1 ];
Send an Alert message whenever an error occurs here Overridden to set default to True
Property methods: AlertErrorDisplayToLogical(), AlertErrorGet(), AlertErrorIsValid(), AlertErrorLogicalToDisplay(), AlertErrorNormalize(), AlertErrorSet()
property EndpointURL as %String);
The complete URL of this Business Service.
E.g. http://server:port/csp/itk/ITK.Framework.Service.SOAPRequestHandler.cls
Property methods: EndpointURLDisplayToLogical(), EndpointURLGet(), EndpointURLIsValid(), EndpointURLLogicalToDisplay(), EndpointURLLogicalToOdbc(), EndpointURLNormalize(), EndpointURLSet()
property FaultVocabulary as %String [ Required ];
Vocabulary to use for creating fault messages from this Service.
Property methods: FaultVocabularyDisplayToLogical(), FaultVocabularyGet(), FaultVocabularyIsValid(), FaultVocabularyLogicalToDisplay(), FaultVocabularyLogicalToOdbc(), FaultVocabularyNormalize(), FaultVocabularySet()
property HttpStatus as %Integer [ Transient ];
The integer code of the HTTP status (if blank/0, then is 200 OK)
Property methods: HttpStatusDisplayToLogical(), HttpStatusGet(), HttpStatusIsValid(), HttpStatusLogicalToDisplay(), HttpStatusNormalize(), HttpStatusSet()
property MaxFileSizeMB as %Float [ InitialExpression = 5 , Required ];
Maximum SOAP Body size that should be processed. If size exceeds this, a SOAP fault will be returned.
Property methods: MaxFileSizeMBDisplayToLogical(), MaxFileSizeMBGet(), MaxFileSizeMBIsValid(), MaxFileSizeMBLogicalToDisplay(), MaxFileSizeMBNormalize(), MaxFileSizeMBSet()
property PromoteITKExtensions as %String [ InitialExpression = "SwitchQueueMode" ];
Inform connecting application about any extened ITK capabilities which may be offered from this ITK service Entensions available comprise: SwitchQueueMode - allows an application to determine the Subcription Pull status of its devices Business Operations UseBinarySOAP - compresses data exchanged between ITK applications
Property methods: PromoteITKExtensionsDisplayToLogical(), PromoteITKExtensionsGet(), PromoteITKExtensionsIsValid(), PromoteITKExtensionsLogicalToDisplay(), PromoteITKExtensionsLogicalToOdbc(), PromoteITKExtensionsNormalize(), PromoteITKExtensionsSet()
property SOAPBodyEncrypted as %String (VALUELIST = ",Required,Ignore") [ InitialExpression = "Ignore" , Required ];
If Required, request will be rejected if SOAP Body is not encrypted.
Property methods: SOAPBodyEncryptedDisplayToLogical(), SOAPBodyEncryptedGet(), SOAPBodyEncryptedIsValid(), SOAPBodyEncryptedLogicalToDisplay(), SOAPBodyEncryptedLogicalToOdbc(), SOAPBodyEncryptedNormalize(), SOAPBodyEncryptedSet()
property SignedHeaders as %Integer (MINVAL = 0) [ InitialExpression = 0 , Required ];
The SOAP sections that MUST be signed in the incoming message.
If any of these is not found to be signed, a SOAP fault will be returned.

Codes for individual segments are as follows:
None 0
SoapBody 1
Timestamp 2
Action 4
FaultTo 8
From 16
MessageId 32
RelatesTo 64
ReplyTo 128
To 256

If mutiple sections are signed, specify sum of individual codes.
E.g. if Timestamp, Action and From are signed, use 22 (2+4+16).

If 0, the check for Username to be same as Subject of X509 Certificate will also be skipped.
Property methods: SignedHeadersDisplayToLogical(), SignedHeadersGet(), SignedHeadersIsValid(), SignedHeadersLogicalToDisplay(), SignedHeadersNormalize(), SignedHeadersSet()
property SynchronousTimeout as %Float [ InitialExpression = -1 ];
Timeout for sysncronous requests
Property methods: SynchronousTimeoutDisplayToLogical(), SynchronousTimeoutGet(), SynchronousTimeoutIsValid(), SynchronousTimeoutLogicalToDisplay(), SynchronousTimeoutNormalize(), SynchronousTimeoutSet()
property TargetConfigName as %String (MAXLEN = 1000);
Configuration item to which to send messages
Property methods: TargetConfigNameDisplayToLogical(), TargetConfigNameGet(), TargetConfigNameIsValid(), TargetConfigNameLogicalToDisplay(), TargetConfigNameLogicalToOdbc(), TargetConfigNameNormalize(), TargetConfigNameSet()
property WSSecurityPassword as %String (VALUELIST = ",Required,Ignore") [ InitialExpression = "Ignore" , Required ];
If True, the UserNameToken and Password will be verified against registered Cache User Credentials. Before making this Required, make sure that the expected Usernames are setup as Cache users in advance.
Property methods: WSSecurityPasswordDisplayToLogical(), WSSecurityPasswordGet(), WSSecurityPasswordIsValid(), WSSecurityPasswordLogicalToDisplay(), WSSecurityPasswordLogicalToOdbc(), WSSecurityPasswordNormalize(), WSSecurityPasswordSet()
property WebServiceClassName as %String;
Property methods: WebServiceClassNameDisplayToLogical(), WebServiceClassNameGet(), WebServiceClassNameIsValid(), WebServiceClassNameLogicalToDisplay(), WebServiceClassNameLogicalToOdbc(), WebServiceClassNameNormalize(), WebServiceClassNameSet()
property WebServiceName as %String;
Property methods: WebServiceNameDisplayToLogical(), WebServiceNameGet(), WebServiceNameIsValid(), WebServiceNameLogicalToDisplay(), WebServiceNameLogicalToOdbc(), WebServiceNameNormalize(), WebServiceNameSet()


classmethod AddNamespacesToBody(pRequestBody As %GlobalCharacterStream, pNSList As %ArrayOfDataTypes, ByRef pNSEnhancedBody As %GlobalCharacterStream) as %Status
abstract method AuthorizeRequest(Output invocationPattern) as %Boolean
Implemented by derived classes
method CreateSOAPHeader() as %SOAP.Addressing.Properties
method CreateSecurityHeader() as %Status
method DetermineDistributionMode() as %String
abstract method DetermineGenericService(Output pClass As %String, Output pMethod As %String)
Implemented by derived classes
method ExtractTrackingId(doc As %GlobalCharacterStream) as %String
method GetEnvelopeNamespaces(Output nsList As %ArrayOfDataTypes) as %Status
classmethod IsSOAPNS(ns As %String) as %Boolean
classmethod MakeFault(pFaultCode As %String, pFaultString As %String, pDetail As %String = "", pFaultActor As %String = "", pStatus As %Status = "") as %SOAP.Fault
Create a SOAP fault. Usually returned by ReturnFault method. (overridden from base class)
method MakeFaultHeader()
method MakeResponseHeader()
method MakeStandardResponse(ByRef pStream As %GlobalCharacterStream)
classmethod MakeStatusFault(pFaultCode As %String, pFaultString As %String, pStatus As %Status = "", pFaultActor As %String = "") as %SOAP.Fault
Create a SOAP fault based on a %Status value. (overridden from base class)
method OnAdapterHTTPResponse(ByRef pStatus As %Status, ByRef pHTTPResponseStatus As %String, ByRef pBodyLen As %Integer, ByRef pResponseBodyStream As %Stream.Object, Output pMainResponseHeader As %String = "", ByRef pHeaderExtra As %String)
Ensure we send an appropriate HTTP response if there is an error This is an ITK requirement that a SOAP Fault is returned as a HTTP Error
classmethod OnGetConnections(Output pArray As %String, pItem As Ens.Config.Item)
Return an array of connections for drawing lines on the config diagram
method OnProcessInput(requestBody As %GlobalCharacterStream, ByRef responseBody As %GlobalCharacterStream, pAction As %String) as %Status
Inherited description: Override this method to process incoming data. Do not call SendRequestSync/Async() from outside this method (e.g. in a SOAP Service or a CSP page).
method Process(pAction As %String, ByRef request, needHeaders As %Boolean = 1)
Inherited description: Process a SOAP request. Initialize must be called first.
The pAction argument contains the value of SOAPAction header.
The request argument contains the SOAP request. For a normal SOAP request, the request argument will be a stream containing the request. For a SOAP with Attachments format request, the request argument will be a multidimensional array of %CSP.Streams that is subscripted by the position in the original multipart message. request(1) is the SOAP message.
The needHeaders argument specifies if HTTP headers need to be output before the SOAP message. Normally the transport class will be responsible for any transport such as HTTP headers.
If the SoapFault property is set up before calling Process, then a SOAP fault is written instead of calling the web method.
The SessionCookie property may be set before calling Process to force value of SessionCookie. This method is meant to be used by SOAP transport classes.
method ProcessBody(pAction As %String, requestBody As %GlobalCharacterStream, ByRef responseBody As %GlobalCharacterStream) as %Boolean
Inherited description: The ProcessBody method of %SOAP.WebService will be passed the request message body as a character stream and will return the response message body in another character stream.
The return value is 1 (true) if the body was processed and a response stream produced. If 0 is returned the %SOAP.MsgDescriptor class will be invoked as usual. If an error occurs during the processing of the request, then a fault should be returned in the usual way using the ReturnFault method.
The arguments to this method are:
action is the SOAPAction for the SOAP request.
requestBody is the body of the SOAP request.
responseBody is a character stream to which the body of the SOAP response will be written.

classmethod ProcessDistributionEnvelope(pRequestBody As %Stream, Output pDE As %String, Output pPayload As %Stream) as %Status
Ensures the DE passes the basic rules set Note: DistributionEnvelope is detected by the work DistributionEnvelope. To make 100% this should look for the namespace declaration
classmethod ValidateDistributionEnvelope(pAction As %String, pDE As EnsLib.EDI.XML.Document, pServiceDefinition As EnsLib.ITK.Setup.ServiceDefinition)
This method is call if there is a distribution envelope to validate it Note: Technically this is not full distribution envelope validation, but we will have this with Schema based XML validation
method ValidateEncryption() as %Status
method ValidateSignature() as %Status
method ValidateWSAddressHeader(pAction As %String, pBehaviorType As %String, pPattern As %String) as %Status
Validate SOAP Header 1. MessageId must be present 2. To must be present and same as EndpointURL 3. Action must be present and same as SOAPAction
method ValidateWSSecurityHeader(pAction As %String, pPattern As %String, Output pCreated As %String, Output pExpires As %String) as %Status
Validate SOAP Security Header If SECURITYIN = "IGNORE": Do nothing If SECURITYIN = "REQUIRE": Raise Fault if Security Header missing Validate fields if Security Header is present - Takes care of the scenario SECURITYIN = "ALLOW" 1. Timestamp (Created) must be present 2. Username must be present 3. Validate Signature 4. Validate Encryption
classmethod captureNamespaces(tree, node, ByRef ns, ByRef nsExternal, iterate=0)

Inherited Members

Inherited Properties

Inherited Methods