WSDLPlugin Reference/en
Inhaltsverzeichnis
Introduction[Bearbeiten]
The WSDL import plugin imports a service description WSDL and generates a library of actions which call these service operations. In addition, datatypes and containers needed as input/output data are generated.
Example Usage[Bearbeiten]
w3schools: Temperature Converter[Bearbeiten]
The following uses one of the standard examples from the w3 consortium, for which both the WSDL is public and a service is provided to test against.
The service converts a value given in degrees Celsius and returns the corresponding Fahrenheit value.
This is only a demo: as such it is not really useful: expecco can do this thousand times faster via the expression: "10 degreesCelsius asFahrenheit".
But that is not the point here - the point is to get a super-simple example, which really connects to an outside service and returns some data.
The URL which describes the service is: "https://www.w3schools.com/xml/tempconvert.asmx?WSDL" and that document describes the two operations named "CelsiusToFahrenheit" and "FahrenheitToCelsius".
Step1: Import the WSDL[Bearbeiten]
- Select "Plugins" -> "Import" -> "WSDL Services" -> "Import Definitions from URL". The menu item is deeply nested and a bit hard to find, but you'll have to do this only once.
- Enter the above URL ("https://www.w3schools.com/xml/tempconvert.asmx?WSDL") into the dialog.
- Next, a dialog asks how those definitions should be imported.
- You can either import the definitions into the current project (i.e. as actions directly in the current project), or alternatively into an imported sub-library.
- Click on "Import".
- Next, a dialog asks if additional actions for packing/unpacking the response containers should be generated.
- Click on "Yes".
- Wait a little, while the URL is fetched, and the actions are generated...
After the import, you'll find the following elements in your suite:
- Service API
- contains action blocks to call the operations (in this case, the two convert operations).
- Inputs and outputs will convert the soap container data into more useful expecco values.
- Low Level
- contains the low-level SOAP call actions.
- Types
- contains data type definitions for types as needed and declared in the WSDL.
- Data Instantiation
- contains actions to instantiate values as passed to SOAP operations (i.e. to construct composite objects as expected by the SOAP operation as incoming data)
- Data Extraction
- actions to extract field values from data received from SOAP operations (i.e. to extract fields from composite objects as returned by SOAP operations)
- wsdl
- an attachment, which contains the retrieved WSDL document. For reference and documentation only.
In general, there is no need to care for those additional actions and types in when importing such a library into another project; your suite will typically only use the actions found in the "Service API" folder, and sometimes those for data instantiation and field extraction.
Step2: Test the Operations[Bearbeiten]
The WSDL usually already contains the endpoint of the service. That is the URL under which the service can be reached.
The generated SOAP call actions will contact this service endpoint by default. However, they will also have an additional input pin named "__url__" which can be given the URL of the endpoint to use. You can leave this input unconnected for the default URL, or freeze it to a constant or variable value, or provide the URL dynamically at execution time from another step.
Now select the generated "CelsusToFahrenheit" action's "Test/Demo" page, give the "Celsius_in" pin some value (say: "100") and test-run it.
If all goes well, the execution should pass and there should be the value of "212" at the output pin. Notice, that the action takes roughly 0.5 seconds to execute (on a slow DSL-connected home network) - after all it is a remote call to a server somewhere in the world.
Step3: Save the Library[Bearbeiten]
You may add additional documentation or README attachments to the library. Then save it (eg. as "TemperatureConvert.ets").
Step4: Use the Library in other Projects[Bearbeiten]
Open a new project, and import the saved "TemperatureConvert.ets". Then use the actions from "Service API" just like any other action.
Authentication[Bearbeiten]
If a web service requires authentication, user name and password values can be passed either by:
- defining environment variables named "SOAP_USER" and "SOAP_PASSWORD", which are visible and present at the time the low-level SOAP action is executed.
These variables can be created either locally inside the calling action's compound action, or inside the imported service library, or as globals in the suite's top environment. The type of these variable are String.
- (only in 21.2 and later) adding pins named "__user__" and "__password__" to the low-level operation,
and providing these pins with user and password string values in the step.
Support for a user and password pins is new with version 21.2.
Currently only HTTP Basic Authentication is supported.
SOAP Timeouts[Bearbeiten]
By default, SOAP actions have a timeout of 30s. That means that if there will be no response from the service after 30 seconds, the SOAP action will report a timeout error.
The timeout can be changed either by:
- defining an environment variable named "SOAP_TIMEOUT", which is visible and present at the time the low-level SOAP action is executed. This variable can be created either locally inside the calling action's compound action, or inside the imported service library, or as global in the suite's top environment. The type of the variable can be TimeDuration or Number. If numeric, it will be the number of seconds. If it has a value of nil, no timeout is effective, and the operation will wait forever (unless there is a timeout on the step in the diagram)
- (only in 21.2 and later) adding pin named "__timeout__" to the low-level operation, and provide a timeDuration or number of seconds or nil to it. With nil, no timeout is effective and the action waits internally "forever". However, you may of course add a timeout to the step (in the diagram where the SOAP action is present).
Support for a timeout pin is new with version 21.2.
By providing different SOAP_TIMEOUT values in the compound action which uses those SOAP actions, these times can be adjusted to the need of individual operations.
I.e. assuming that the CelsiusToFahrenheit takes much longer than the other operation, create a new compound action, put the CelsiusToFahrenheit into its diagram, connect the input and output pins from the SOAP action to the compound action's pins, and define a SOAP_TIMEOUT variable local to the compound. Then this timeout is used for that action only, and can be different from any default timeout as specified in the suite.
Best Practice Timeout Handling[Bearbeiten]
If operations have a wide variation in timing, it is probably best to set the global timeout to nil (i.e. no timeout at the low level), and instead set individual timelimits at the steps which call those operations.
Place those into separate variables (i.e. SOAP_TIME_FOR_OPERATION1, SOAP_TIME_FOR_OPERATION2, etc.) and freeze the timeLimits to those variables. Then it is easy to change individual times, and it is also easy to initialize those values automatically (eg. by reading them from a CSV attachment, or by adding an action which multiplies all values by a factor).
SOAP Protocol Traces[Bearbeiten]
To see the in and out messages, go to "Extras " - "Settings " - "Execution " - "Tracing ", and check the "Show SOAP Requests on Transcript " toggle.
Make sure that the Logger's threshold is also set to at least "Info". Otherwise, the SOAP log messages are filtered by the logger.
