You are viewing the documentation for Blueriq 14. Documentation for other versions is available in our documentation directory.

The AQ_SoapServiceClient service calls a SOAP webservice. It is similar to the AQ_WebServiceClient, but it handles only SOAP requests. AQ_SoapServiceClient leverages on spring-ws WebServiceTemplate which has the possibility to add additional security interceptors (http://docs.spring.io/spring-ws/site/reference/html/security.html). The features of the AQ_SoapServiceclient are listed below:

  • Basic authentication
  • Timeout setting
  • UsernameToken Profile V1.0
  • X.509 Token Profile V1.0
    • Signing
    • Timestamp
    • Encryption
  • Logging request / response
  • Exception handling for socket timeout
  • Exception handling for SoapFault
  • Map SoapFault to profile
  • Sending and receiving attachments
  • Dynamic urls

Parameters


NameDescriptionTypeRequiredDirectionSelect module
soapServiceName of SOAP service, with the module where it was defined.Module ElementtrueInputtrue
operationThe name of the operation that needs to be called.StringtrueInputfalse
urlThe URL of the SOAP webservice.String ExpressionfalseInputfalse
connectionOverrideOverride the name of the used connection configuration from application.properties. This parameter may be used to share a configuration among multiple AQ_SoapServiceClient calls.String ExpressionfalseInputfalse
mappingName of the data mapping to use, if a separate module is used for the WSDL.Data mappingfalseBiDirectionalfalse
usernameUsername to access the service.StringfalseInputfalse
passwordPassword to access the service.StringfalseInputfalse
soapFaultThe type of the instance that should be updated when a soap fault occurs.EntitytrueOutputfalse
soapFaultCodeThe attribute of the instance which should be updated with the soap fault code when a soap fault occurs.AttributetrueOutputfalse
soapFaultMessageThe attribute of the instance which should be updated with the soap fault message when a soap fault occurs.AttributetrueOutputfalse
SoapFaultRoleThe attribute of the instance which should be updated with the soap fault roles object (SOAP 1.2), or the actor object (SOAP 1.1).AttributefalseOutputfalse
SoapFaultDetailsThe attribute of the instance which should be updated with the soap fault roles details object, this could either contain a text value or an xml message, which will be stored as text in the given attributeAttributefalseOutputfalse
connectionConnection to retrieve/store documents from/on.StringfalseBiDirectionalfalse
fileListThe file(s) which will be attached and send.Multivalued Entity ExpressionfalseInputfalse
fileRelationThe relation to hold returned files.RelationfalseOutputfalse
persistenceThe persistence parameter indicates whether the system should clean up files at the end of the request (MemoryConnection)/session (FileSystemConnection).Temporary / PermanentfalseInputfalse
caseIdThe CaseId of the case the received documents belong to.String ExpressionfalseOutputfalse
fileThe type of the instance that should be updated when a file is received.EntityfalseOutputfalse
fileIdThe attribute of the instance which should be updated with the file id when a file is received.AttributefalseOutputfalse
fileContentIdThe attribute of the instance which should be updated with the file content id when a file is received.AttributefalseOutputfalse
fileNameThe attribute of the instance which should be updated with the file name when a file is received.AttributefalseOutputfalse
fileTypeThe attribute of the instance which should be updated with the file type when a file is received.AttributefalseOutputfalse
fileSizeThe attribute of the instance which should be updated with the file size when a file is received.AttributefalseOutputfalse
fileCreatedByThe attribute of the instance which should be updated with the file created by attribute when a file is received.AttributefalseOutputfalse
fileCreationDateThe attribute of the instance which should be updated with the file creation date when a file is received.AttributefalseOutputfalse


Exit events

NameDescriptionType
OkWhen the SOAP request is executed successfully.Continue
Timeout When the SOAP request returns a timeout exception.Continue
SoapFault When the SOAP request returns a SOAP fault exception.Continue
ErrorWhen the SOAP request returns other errors.Cancel

Exit events

Make sure to map these events and connect them in your flowing when migrating from AQ_Webserviceclient.

Otherwise a timeout will trigger the default exit, not the exception exit.

The exit events can be found at the top right corner of the service call:

Behaviour default exit node

All unmapped events will be redirected to the default exit node of the service call, even errors. Therefore it is recommended to always map all possible expected exit events.

When all expected events are mapped, the default exit node will be removed from the service call as exit event.

Note on persistence

The following rules apply for the Persistence parameter:
Connection TypePersistenceClusteredNotes
MemoryTemporaryNoThe file is stored temporarily for the duration of the current request. At the end of the request the file is deleted. Memory connections and temporary persistence should be used when an uploaded/received file is immediately sent to a 3rd party system during the same request.
MemoryTemporaryYes
MemoryPermanentNoPermanently storing files in a memory connections is not allowed. The Runtime will throw an exception when trying to permanently store files in a memory connection
MemoryPermanentYes
Other / FileSystemTemporaryNoThe file is stored temporarily for the duration of the current session. At the end of the session the file is deleted.
Other / FileSystemTemporaryYesThe file is stored temporarily for the duration of the current session and a Quartz job is scheduled to delete the file.
Other / FileSystemPermanentNoThe file is permanently stored in the connection and must be explicitly deleted when no longer needed.
Other / FileSystemPermanentYes

Configuration in application.properties


The default SOAP security properties can be defined using the following properties:

NameDescriptionType
blueriq.security.keystore.locationThe path to the keystore file. The keys in the keystore will be used for signing and/or encrypting soap messages.String
blueriq.security.keystore.passwordThe password for the keystore file.String
blueriq.security.truststore.locationThe path to the trust store containing the public keys/certificates of external hosts that should be trusted
blueriq.security.truststore.passwordThe password for the truststore file.



blueriq.soap.security.encryption.[name].keystore-aliasThe alias of the certificate in the keystore that will be used for encrypting the soap message.String
blueriq.soap.security.encryption.[name].parts

The parts that should be encrypted. By default, the content of the SOAP body is encrypted. The syntax of this property is:

  • multiple values must be separated by a semi-colon
  • each value may be preceded by a mode specifier, either {Content} or {Element}. If not specified it defaults to {Content}

  • the mode specifier may be followed by a namespace specifier. If omitted, it defaults to the SOAP namespace.

  • the value must contain the name of the element which must be encrypted


For example, the value {Content}{http://example.org/paymentv2}CreditCard;{Element}{None}Username has the following meaning:

  • the content of the CreditCard element in the http://example.org/paymentv2 namespace will be encrypted. The CreditCard element itself is not encrypted, so any attributes on this element will be in plain text 
  • the Username element with no namespace is encrypted. The element itself is also encrypted, so any attributes will not be visible in plain text.
String
blueriq.soap.security.encryption.[name].identifierSpecifies in what way the encryption key is identified. Possible values are: IssuerSerial, DirectReference, X509KeyIdentifier, Thumbprint, SKIKeyIdentifierString
blueriq.soap.security.encryption.[name].algorithm

The encryption algorithm to be used. Possible values are:

String



blueriq.soap.security.signature.[name].keystore-aliasThe alias of the private key in the keystore that will be used to sign the SOAP message.String
blueriq.soap.security.signature.[name].keystore-passwordThe password required to read the key from the keystore.String
blueriq.soap.security.signature.[name].partsThe parts that need to be signed. See the equivalent property for encryption for syntax and details.String
blueriq.soap.security.signature.[name].identifierSpecifies in what way the signature key is identified. Possible values are: IssuerSerial, DirectReferenceString
blueriq.soap.security.signature.[name].validate-responseWhether to validate the response, in case the SOAP service includes a signature configuration in the response.Boolean



blueriq.soap.security.timestamp.[name].timestampPrecisionInMillisecondsWhether the timestamp precision should be in milliseconds.Boolean



blueriq.soap.security.usernametoken.[name].usernameThe username sent in the token.String
blueriq.soap.security.usernametoken.[name].passwordThe password sent in the token.String
blueriq.soap.security.usernametoken.[name].password-typeWhether the password is sent as plain text or digest. Possible values: PasswordText, PasswordDigestString
blueriq.soap.security.usernametoken.[name].createdWhether to include a Created timestamp in the tokenBoolean
blueriq.soap.security.usernametoken.[name].nonceWhether to include a Nonce in the tokenBoolean


Soap connection properties:

NameDescriptionType
blueriq.connection.[serviceName].soap.urlThe URL of the SOAP web service.String
blueriq.connection.[serviceName].soap.usernameThe username for basic authentication.String
blueriq.connection.[serviceName].soap.passwordThe password for basic authentication.String
blueriq.connection.[serviceName].soap.security.implementationsA comma separate list of security implementations (defined using the blueriq.soap.security.* properties)String[]
blueriq.connection.[serviceName].soap.timeoutThe timeout in milliseconds.Integer
blueriq.connection.[serviceName].soap.client-certificate-alias-nameUses the certificate that is defined by the alias name from the configured keystore(check security properties on how to specify the keystore).String

Troubleshoot

When migrating from the AQ_webserviceClient to the AQ_SoapserviceClient, you might run into an error. 

"IllegalStateException: Security type for service name is null. Did you forgot to add this to the properties file? "

In your application.properties there's still a line that refers to the old webservice client. Search for: webservice.soap.security.implementations=

This line should be removed from your properties file. That should solve the problem. 

How the URL is determined

  1. if the connectionOverride parameter is defined, the settings of that connection are used
  2. if a connection with the same name as the service call is defined, the settings of that connection are used
  3. if the url parameter is defined, the value resulting from evaluating the url expression is used
  4. otherwise, the URL in the WSDL is used