InterSystems IRIS for Health 2021.1Opens in a new window > Class Reference > HSLIB namespace > HS.IHE.Common.Services.SOAPServer.Base

HS.IHE.Common.Services.SOAPServer.Base

class HS.IHE.Common.Services.SOAPServer.Base extends HS.HC.Util.Trace.Helper, EnsLib.SOAP.Service

Property Inventory (Including Private)

Method Inventory (Including Private)

Parameters

parameter ADAPTER;
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.
parameter MUSTUNDERSTANDACTION = 1;
parameter SECURITYIN = allow;
Inherited description: The SECURITYIN parameter controls the treatment of a WS-Security header in the input SOAP message. The possible values of SECURITYIN are ALLOW, NOHEADER, IGNORE, IGNOREALL 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-Security header and verify the header on input.
- The value of IGNOREALL will ignore any WS-Security headers in the input including the UsernameToken.

- The value of NOHEADER will REALLY ignore any WS-Security headers in the input including the UsernameToken.

Note that if validation of the Security header is enabled (ALLOW or REQUIRE), then a CA file, named iris.cer, containing the trusted root X509 certificates should be put in the InterSystems IRIS manager directory if signature verification or decryption is to be performed. An optional Certificate Revocation List (iris.crl) may also be put in the InterSystems IRIS manager directory.
parameter SETTINGS = ResourceRequired,UserMaximumRequests,UserInterval,UserIntervalUnits,IPAddressMaximumRequests,IPAddressInterval,IPAddressIntervalUnits,SAMLProcessor,OrgURLAttributeCode,UseSAMLUserName,RequireValidSAMLToken,InvalidTokenLogging,XMLValidator,AdditionalSecurityClass;
Inherited description: Can't do grace period without an OnTask loop
parameter WSADDRESSING = OFF;
Inherited description: WSADDRESSING parameter controls automatic generation of WS-Addressing headers.

Properties (Including Private)

property AdditionalSecurityClass as %Dictionary.Classname;
Class to perform additional security validation Specific callbacks include PreProcessor(pService as HS.IHE.Common.Services.SOAPServer.Base,ByRef pFault) as %Status this method allows custom validation to cause a soap fault on the service ReturnFault(fault As %SOAP.Fault, pService As HS.IHE.Common.Services.SOAPServer.Base) This method allows the additional user code to be added during a return fault call
Property methods: AdditionalSecurityClassGet(), AdditionalSecurityClassIsValid(), AdditionalSecurityClassSet()
property IPAddressInterval as %String (DISPLAYLIST = ",Second,Minute,Hour,Day,Week,Month,Year", VALUELIST = ",ss,mi,hh,dd,wk,mm,yy");
Indicate the rolling time period for which maximum requests by IP should be counted (defaults to 'Hour' if unspecified).
Property methods: IPAddressIntervalDisplayToLogical(), IPAddressIntervalGet(), IPAddressIntervalIsValid(), IPAddressIntervalLogicalToDisplay(), IPAddressIntervalLogicalToOdbc(), IPAddressIntervalNormalize(), IPAddressIntervalSet(), IPAddressIntervalUnitsDisplayToLogical(), IPAddressIntervalUnitsGet(), IPAddressIntervalUnitsIsValid(), IPAddressIntervalUnitsLogicalToDisplay(), IPAddressIntervalUnitsNormalize(), IPAddressIntervalUnitsSet()
property IPAddressIntervalUnits as %Integer [ InitialExpression = 1 ];
Indicate the number of units for the selected IP enforcement interval.
Property methods: IPAddressIntervalUnitsDisplayToLogical(), IPAddressIntervalUnitsGet(), IPAddressIntervalUnitsIsValid(), IPAddressIntervalUnitsLogicalToDisplay(), IPAddressIntervalUnitsNormalize(), IPAddressIntervalUnitsSet()
property IPAddressMaximumRequests as %Integer;
Indicate the maximum number of IP-based requests supported. A value less than 1 (including an empty value) disables IP-based enforcement.
Property methods: IPAddressMaximumRequestsDisplayToLogical(), IPAddressMaximumRequestsGet(), IPAddressMaximumRequestsIsValid(), IPAddressMaximumRequestsLogicalToDisplay(), IPAddressMaximumRequestsNormalize(), IPAddressMaximumRequestsSet()
property InvalidTokenLogging as %String (VALUELIST = ",None,Trace,Info,Warning") [ InitialExpression = "Warning" ];
This setting controls the log level used to log information about validation failures. The default setting is Warning.
Property methods: InvalidTokenLoggingDisplayToLogical(), InvalidTokenLoggingGet(), InvalidTokenLoggingIsValid(), InvalidTokenLoggingLogicalToDisplay(), InvalidTokenLoggingLogicalToOdbc(), InvalidTokenLoggingNormalize(), InvalidTokenLoggingSet()
property MessageXUAProcessor as HS.HC.IHE.XUA.Processor;
SAML processor to be used for this messsage (based on GetSAMLProcessor and DEFAULT)
Property methods: MessageXUAProcessorGet(), MessageXUAProcessorGetSwizzled(), MessageXUAProcessorIsValid(), MessageXUAProcessorNewObject(), MessageXUAProcessorSet()
property OrgURLAttributeCode as %String;
SAML Processing: For obscure use cases where the organization(-id) attribute name is not "urn:oasis:names:tc:xspa:1.0:subject:organization-id" Use Class:Method to locate the OrganizationOID or URL from the assertion [equivalent to organization = ##class(Class).Method(pAssertion)] Example Value HS.IHE.XUA.SHINNY.Processor:GetOrganizationID
Property methods: OrgURLAttributeCodeDisplayToLogical(), OrgURLAttributeCodeGet(), OrgURLAttributeCodeIsValid(), OrgURLAttributeCodeLogicalToDisplay(), OrgURLAttributeCodeLogicalToOdbc(), OrgURLAttributeCodeNormalize(), OrgURLAttributeCodeSet()
property RequireValidSAMLToken as %Boolean [ InitialExpression = 1 ];
If this class is receiving and processing SAML Assertions (where a SAMLProcessor is defined), this flag controls whether a SAML token which fails to pass validation in the ValidateSAML() method of the specified SAMLProcessor will still be processed. The default is true, meaning that a failure here will throw a SOAP fault. Without a SAMLProcessor defined, this setting does nothing.
Property methods: RequireValidSAMLTokenDisplayToLogical(), RequireValidSAMLTokenGet(), RequireValidSAMLTokenIsValid(), RequireValidSAMLTokenLogicalToDisplay(), RequireValidSAMLTokenNormalize(), RequireValidSAMLTokenSet()
property ResourceRequired as %String;
If specified, then users of this web service must have this resource.
Property methods: ResourceRequiredDisplayToLogical(), ResourceRequiredGet(), ResourceRequiredIsValid(), ResourceRequiredLogicalToDisplay(), ResourceRequiredLogicalToOdbc(), ResourceRequiredNormalize(), ResourceRequiredSet()
property SAMLData as HS.IHE.XUA.SAMLData [ Private , Transient ];
Property to contain the results returned from the call to <..MessageXUAProcessor>:ProcessSAML() call.
Property methods: SAMLDataGet(), SAMLDataGetObject(), SAMLDataGetObjectId(), SAMLDataGetSwizzled(), SAMLDataIsEmpty(), SAMLDataIsValid(), SAMLDataNewObject(), SAMLDataSet(), SAMLDataSetObject(), SAMLDataSetObjectId(), SAMLDataUnSwizzle()
property SAMLProcessor as %Dictionary.Classname;
Class to process incoming SAML tokens. This class should extend HS.HC.IHE.XUA.Processor or deprecated HS.CHIxP.SAML.SAMLProcessor.
Property methods: SAMLProcessorGet(), SAMLProcessorIsValid(), SAMLProcessorSet()
property UseSAMLUserName as %Boolean [ InitialExpression = 1 ];
If this class is receiving and processing SAML Assertions, this flag controls whether the class should use the "UserName" property retrieved from the SAML Assertion for auditing purposes. The default is true, but in some cases the value of $Username may be preferred.
Property methods: UseSAMLUserNameDisplayToLogical(), UseSAMLUserNameGet(), UseSAMLUserNameIsValid(), UseSAMLUserNameLogicalToDisplay(), UseSAMLUserNameNormalize(), UseSAMLUserNameSet()
property UserInterval as %String (DISPLAYLIST = ",Second,Minute,Hour,Day,Week,Month,Year", VALUELIST = ",ss,mi,hh,dd,wk,mm,yy");
Indicate the rolling time period for which maximum requests by user should be counted (defaults to 'Hour' if unspecified).
Property methods: UserIntervalDisplayToLogical(), UserIntervalGet(), UserIntervalIsValid(), UserIntervalLogicalToDisplay(), UserIntervalLogicalToOdbc(), UserIntervalNormalize(), UserIntervalSet(), UserIntervalUnitsDisplayToLogical(), UserIntervalUnitsGet(), UserIntervalUnitsIsValid(), UserIntervalUnitsLogicalToDisplay(), UserIntervalUnitsNormalize(), UserIntervalUnitsSet()
property UserIntervalUnits as %Integer [ InitialExpression = 1 ];
Indicate the number of units for the selected user enforcement interval.
Property methods: UserIntervalUnitsDisplayToLogical(), UserIntervalUnitsGet(), UserIntervalUnitsIsValid(), UserIntervalUnitsLogicalToDisplay(), UserIntervalUnitsNormalize(), UserIntervalUnitsSet()
property UserMaximumRequests as %Integer;
Indicate the maximum number of user requests supported. A value less than 1 (including an empty value) disables user-based enforcement.
Property methods: UserMaximumRequestsDisplayToLogical(), UserMaximumRequestsGet(), UserMaximumRequestsIsValid(), UserMaximumRequestsLogicalToDisplay(), UserMaximumRequestsNormalize(), UserMaximumRequestsSet()
property XMLValidator as %Dictionary.Classname;
Class to perform xsd validation on request / response
Property methods: XMLValidatorGet(), XMLValidatorIsValid(), XMLValidatorResponseGet(), XMLValidatorResponseIsValid(), XMLValidatorResponseSet(), XMLValidatorSet()
property XMLValidatorResponse as %Dictionary.Classname;
If the service is interested in stopping based on the XML validation response, it can review XMLValidatorResponse results (of type HS.Util.XML.Validator)
Property methods: XMLValidatorResponseGet(), XMLValidatorResponseIsValid(), XMLValidatorResponseSet()

Methods (Including Private)

private method EnforceServiceUsage() as %Status [ Language = objectscript ]
Prevent "denial of service" or similar attacks against a web service. Allow user-defined thresholds based on requesting IP address and/or user name to be defined. Note that if the "UserName" key of ..SAMLData.SAMLInfo is populated, this value will be used as the username for the incoming user.
method GetSAMLProcessor(pSAMLAssertion) as %Status [ Language = objectscript ]
classmethod GetSchema(pAction As %String = "") as %String [ Language = objectscript ]
method InsertAttachements(pRequest As HS.Message.XMLMessage, pAction As %String) as %Status [ Language = objectscript ]
Copy SOAP attachments into request StreamCollection
method MoveAttachments(pResponse As HS.Message.XMLMessage) as %Status [ Language = objectscript ]
Copy response StreamCollection into SOAP attachments
method OnFinalizeProcessBodyNode(pRequest As HS.Message.XMLMessage, pResponse As HS.Message.XMLMessage, pSC As %Status) as %Status [ Language = objectscript ]
Callback after Ensemble messaging but before processing fault
method OnInit() as %Status [ Language = objectscript ]
Ensure that the ..SAMLProcessor class exists and extends HS.HC.IHE.XUA.Processor or deprecated HS.CHIxP.SAML.SAMLProcessor
method OnPreWebMethod() [ Language = objectscript ]
Inherited description: The OnPreWebMethod method will be called before any web method in a web service. OnPreWebMethod cannot return a value and thus cannot change the execution of the web service except by returning a SOAP fault in the same way that a web method would return a SOAP fault. OnPreWebMethod can look at %request, %session and the web service properties to control its behavior. MsgClass is a web service property which is the message descriptor class which contains the web method arguments.
method OnSetAttachmentBody(pAction As %String, pFrom As %Net.MIMEPart, pTo As HS.IHE.Common.Messages.MIMEAttachment) as %Status [ Language = objectscript ]
Callback to copy MIME body into StreamCollection item body
method ProcessBodyNode(pAction As %String = "", pNodeBody As %XML.Node, ByRef pResponseBody As %CharacterStream = $$$NULLOREF) as %Boolean [ Language = objectscript ]
Inherited description: The ProcessBodyNode method of %SOAP.WebService will be passed an %XML.Node instance which is positioned at the child of the Body element of the SOAP which has the contents of the request body. ProcessBodyNode 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.
body is an %XML.Node instance for the contents of the SOAP request body.
responseBody is a character stream to which the body of the SOAP response will be written.

classmethod ReturnFault(fault As %SOAP.Fault, pService As HS.IHE.Common.Services.SOAPServer.Base = $g(%cspsoapservice)) [ Language = objectscript ]
Inherited description: Return the SOAP fault in %SOAP.Fault as the result of this web method call. The ReturnFault method should only be called from the implementation of the WebMethod. This method will not return to its caller. It will act as a Quit from the Web Method with the %SOAP.Fault as the return value.

You can generate a SOAP fault from a web method as in the following example:

  Set fault=##class(%SOAP.Fault).%New()
  Set fault.faultcode=$$$FAULTServer
  Set fault.faultstring="Processing Error"
  Set fault.detail="<e:myError xmlns:e=""some-URI"">app didn't work</e:myError>"
  Do ..ReturnFault(fault) ; will not return
  
method SchemaErrorCount() as %Integer [ Language = objectscript ]
Report the number of errors from schema validation (zero if no validation has been run)
method SchemaErrorString() as %String [ Language = objectscript ]
method SetAddressingOut(pAction) [ Language = objectscript ]
Set the relatesto (which inbound message) and the response action
method ValidateMessage(pRequest="", pAction="", pType="") [ Language = objectscript ]

Inherited Members

Inherited Properties (Including Private)

Inherited Methods (Including Private)

Subclasses

FeedbackOpens in a new window