WSInvokeDL

The WSInvokeDL function makes web services calls when a Web Services Description Language (WSDL) file is compiled with nci_compilewsdl, or when a policy is configured using the Web Services wizard.

Syntax

This function has the following syntax:

[Return] = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, [callProps])

This function returns the value of your target web services call.

Parameters

The WSInvokeDL function has the following parameters:

Table 1. WSInvokeDL function parameters
Parameter	Format	Description
`WSService`	String	This web service name is defined in the `/definitions/service` element of the WSDL file.
`WSEndPoint`	String	The web service endpoint URL of the target web service.
`WSMethod`	String	The web service method defines which method you would like to call in `WSInvokeDL()`.
`WSParams`	Array	The web services operation parameters are defined by `/definitions/message/part` elements in the WSDL file. It comprises an array that contains all of the parameters that are required by the specified web service operation.
`callProps`	String, Boolean, integer	The optional container in which you can set any of the properties, which are listed in the callProps properties section.

callProps properties

Remember: Any options that are set in callProps must precede the actual call to WSInvokeDL.

CacheStub

Caches generated stubs. This value must be set to true if either or both of the following properties are enabled, ReuseHttpClient, MaintainSession.

Examples of usage:

  callProps.CacheStub=true;

  callProps.ReuseHttpClient = true;

CharSet

Sets the encoding other than UTF-8.

Chunked

Divides the packets into small chunks if the server supports the feature. The default property is true.

Tip: If you receive the following error message when running the WSInvokeDL function then set this property to false.

Transport error: 11 Error: Length Required in policy

ConnectionManagerTimeout

version 7.1.0.19+ Sets how long (in milliseconds) a client should wait for a free connection before timing out. The default is 30000 milliseconds.

Example usage:

  callProps.ConnectionManagerTimeout=30000;

Starting with 7.1.0.30, the ConnectionManagerTimeout property has been deprecated and you should use WSTimeout instead.

CustomHeaders

Adds custom header values other than the headings that are already supported in the documentation.

DecryptPassword

Enables the decryption of an encrypted password in a policy.

EnableWSS

Enables Web Service Security. If you specify EnableWSS, you must also specify the following properties:

WSSRepository, which specifies the path location of WSS Repository.
WSSConfigFile, which specifies configuration file for EnableWSS.
WSSPolicyFile, which specifies an optional WS-Policy file.

Example:

callProps.EnableWSS = true;
callProps.WSSRepository= "/opt/IBM/tivoli/impact/dsa/wsdsa/wss";
callProps.WSSConfigFile = "/opt/IBM/tivoli/impact/dsa/wsdsa/wss/conf/Sample03_wss.xml";
callProps.WSSPolicyFile = "/opt/IBM/tivoli/impact/dsa/wsdsa/wss/conf/policy03.xml";

WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, callProps);

Tip: See Web services security for more information on how to configure Web Services Security.

GetHeaders

Retrieves the Web Service headers and returns them in the ResponseHeaders variable.

To retrieve the Web Service headers, use the following:

    callProps.GetHeaders = true;

You can access individual headers with dot or bracket notation. For example, to access the Content-Language header:

    Log(ResponseHeaders);
    ContentLanguage = ResponseHeaders["Content-Language"];
    Log(ContentLanguage);

Sample output:

    Parser log: "Context"=(Content-Language=en-GB, Date=Fri, 24 Feb 2017 16:41:12 GMT, Content-Length=259, Content-Type=text/xml; charset=UTF-8, X-Powered-By=Servlet/3.0)  
    Parser log: en-GB

HandleFault

Is used to manage faults. Fault messages are returned from the web services server to indicate that there is a problem.

HTTP

The default HTTP version is 1.1. You can use this property to set the protocol version to 1.0.

HttpClientVersion

version 7.1.0.37+ Select the HTTP client version. Available versions are 3 and 4. Switching the client version may help resolve performance issues with the HTTP connection. The default version is 3.

Example usage:

callProps.HttpClientVersion = 3;

KeepAlive

Can be used to enable the KeepAlive header. If set to true, connections are kept alive for reuse by multiple sequential requests and responses. If set to false, connections are closed after the response is sent. It requires HTTP 1.1.

Example usage:

  callProps.KeepAlive = true;

LogSoapMessages

You can enable logging of outgoing and incoming soap messages, by setting the LogSoapMessages property to true. This property should only be used for debugging purposes and should not be enabled permanently in a production environment.

  callProps = NewObject();
  callProps.LogSoapMessages = "true";
  WSInvokeDLResult = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, callProps);

The messages will be logged to $IMPACT_HOME/wlp/usr/servers/<server>/logs/messages.log.

MaintainSession

Sets the session management to enabled status. When session management is enabled, the system maintains the session-related objects across the different requests. The parameter must be set to true or false.

MaxConnectionsPerHost

version 7.1.0.19+ Sets the maximum number of parallel connections to a host. This value can be increased if the web service client is experiencing timeouts while waiting for a free connection. This number cannot exceed the value of MaxTotalConnections.

Example usage:

    callProps.MaxConnectionsPerHost=2;

The default value is 2. By default, if two simultaneous connections are in use, for the same host, then additional requests will wait for a free connection to become available. A timeout will occur if the wait period exceeds the connection timeout.

Note: A connection pool is initialized per host on the first request made to that host. Therefore, set MaxConnectionsPerHost to the same value in all policies accessing the same host to ensure a consistent maximum.

MaxTotalConnections

version 7.1.0.30+ The total number of connections for the web service client across all hosts.

Example usage:

    callProps.MaxTotalConnections=20;

The default value is 20. Regardless of the MaxConnectionsPerHost setting, the MaxTotalConnections value controls the total number of connections across all hosts. The sum of the connections per host cannot exceed this value. By default, if twenty simultaneous connections are in use (regardless of which host) then additional requests will wait for a free connection to become available. A timeout will occur if the wait period exceeds the connection timeout.

Password

Specifies the password for basic authentication.

PreemptiveAuth

Enables Preemptive Authentication.

ReuseHttpClient

Enables the underlying infrastructure to reuse the HTTP client if one is available. The ReuseHttpClient is useful if the client is using HTTPS to communicate with the server. The parameter must be set to true or false.

SocketTimeout

version 7.1.0.30+ Specifies how long the client should wait between data packets. If no data is received before the SocketTimeout is reached, the connection will be considered inactive. The default is 60000 milliseconds.

Example usage:

    callProps.SocketTimeout=9000; // Use SocketTimeout instead

Timeout

This property is used in a blocking scenario. The client system times out after the specified amount of time.

You can optionally set a global web Service DSA call timeout property called impact.server.dsainvoke.timeout. The property must be added to the Netcool®/Impact server property file, <servername>_server.props. It is best to use the timeout property on a per policy basis as specified in callProps.Timeout.

The value is set in milliseconds, for example, impact.server.dsainvoke.timeout=30000 (30 seconds).

When you set the properties in any of the .props files, restart theNetcool/Impact server to implement the changes.

If the impact.server.dsainvoke.timeout property is set, all WSInvokeDL calls use the same timeout setting.

TrustCertificate

version 7.1.0.20+ Allows the WSInvokeDL function to connect to an SSL endpoint without having to import the chain into the trust store. The endpoint's SSL certificate must still be valid and not expired:

callProps.TrustCertificate=true;

Username

Specifies the user name for basic authentication.

WSTimeout

version 7.1.0.30+ Specifies how long the client should wait when establishing a connection with the remote host. The default is 60000 milliseconds.

Example usage:

    callProps.WSTimeout=60000;

XMLFactory

version 7.1.0.33+ When set to true, the function will use an internal XML library to generate the SOAP XML payload. This may be useful in resolving compatibility issues with the default XML library.

Example usage:

  callProps.XMLFactory=true;

Examples

Remember: Any options that are set in callProps must precede the actual call to WSInvokeDL.

Apart from its primary usage, the callProps container can be used to enable security. For example, if the basic authentication is enabled through the wizard, the sample policy contains the following lines:

callProps.Username="username";
callProps.Password="password";

The following example shows how to use the WSInvokeDL function to send a message to the target web service.

Example using IPL:

ServiceName = "StockQuote";
EndPointURL = "http://www.webservicex.net/stockquote.asmx";
MethodName = "GetQuote";
ParameterArray = { "IBM" };
callProps = NewObject();

Results = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, callProps);

Example using JavaScript:

ServiceName = "StockQuote";
EndPointURL = "http://www.webservicex.net/stockquote.asmx";
MethodName = "GetQuote";
ParameterArray = [ "IBM" ];

Results = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, [callProps])

Use the DecryptPassword policy parameter to enable the decryption of an encrypted password in a policy that is used with the callProps function:

callProps=NewObject();
callProps.Password="<Web Serice encrypted using nci_crypt>";
callProps.DecryptPassword=true;  
//default is false and must be plain text password.

The password is decrypted at policy runtime and is used in plain text internally to Netcool/Impact.

You can also use the CustomHeaders parameter to add custom http header values other than the headings that are already supported in the documentation.

Headers = NewObject();
Headers.HeaderName1='HeaderValue1';
Headers.HeaderName2='HeaderValue2';
callProps.CustomHeaders=Headers;

Use the HandleFault parameter to handle fault messages.

callProps=NewObject();
callProps.HandleFault=true;

When the default value is false, the policy throws an exception. When the value is true, the policy returns only the fault string message. No fault code is returned.

If the value is true, the return is similar to the following example.

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<Fault>
	<faultstring> some message here 
	</faultstring>
</Fault>

To turn off the formatting and return the message in plain text add the following parameter anywhere in <serverName>_server.props:

impact.wsinvoke.formatfaultmessage=false

The changes are implemented dynamically without restarting the server.