Skip to main content

HS.IHE.Common.Services.SOAPServer.Base

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

Property Inventory

Method Inventory

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 REQUESTVERSION = 1.2;
The REQUESTVERSION parameter specifies the version(s) of SOAP which are supported for a SOAP request. Possible values for the version are 1.1 and 1.2. The value "" specifies that both SOAP 1.1 and SOAP 1.2 are supported. Overriding default from %SOAP.WebService to require 1.2 for IHE
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 SOAPVERSION = 1.2;
The SOAPVERSION parameter specifies the version of SOAP which is supported. The SOAPVERSION parameter effects only the WSDL that is created for this service. The version for which requests are accepted is specified by REQUESTVERSON. Possible values for the version are 1.1 and 1.2. The value "" specifies that both SOAP 1.1 and SOAP 1.2 are supported. Overriding default from %SOAP.WebService to require 1.2 for IHE
parameter WSADDRESSING = OFF;
Inherited description: WSADDRESSING parameter controls automatic generation of WS-Addressing headers.

Properties

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()
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 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()
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(), 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

classmethod FindConfiguration(pOrganizationID="") as HS.IHE.XUA.Config
classmethod GetProcessor(pOrganizationID) as HS.IHE.XUA.Processor
method GetSAMLProcessor(pSAMLAssertion) as %Status
classmethod GetSchema(pAction As %String = "") as %String
method InsertAttachements(pRequest As HS.Message.XMLMessage, pAction As %String) as %Status
Copy SOAP attachments into request StreamCollection
method MoveAttachments(pResponse As HS.Message.XMLMessage) as %Status
Copy response StreamCollection into SOAP attachments
method OnFinalizeProcessBodyNode(pRequest As HS.Message.XMLMessage, pResponse As HS.Message.XMLMessage, pSC As %Status) as %Status
Callback after Ensemble messaging but before processing fault
method OnInit() as %Status
Ensure that the ..SAMLProcessor class exists and extends HS.HC.IHE.XUA.Processor or deprecated HS.CHIxP.SAML.SAMLProcessor
method OnPreWebMethod()
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
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
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))
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
Report the number of errors from schema validation (zero if no validation has been run)
method SchemaErrorString() as %String
method SetAddressingOut(pAction)
Set the relatesto (which inbound message) and the response action
method ValidateMessage(pRequest="", pAction="", pType="")

Inherited Members

Inherited Properties

Inherited Methods

Subclasses

FeedbackOpens in a new tab