0
Call a Generic Webservice
Description
The call webservice part allows you to enable your logicnet-based application to perform a web service call and retrieve a response.
Use
The call webservice part is located in the App Dev dropdown menu in a process node. When you select the part, enter the connection information for the webservice to which to connect. The system can store the response in the application context.
Editor Fields
| Field Name | Description | Type/Options | Optional/Mandatory |
| Result code path | This is the path of the data object in which the result code will be saved. | Data Object | Mandatory |
| Response type | With this option you can define if the response is presented as a downloadable file or a data object. | Data Object | File | Mandatory |
| Filename | This is the name of the file to download if [Response type] is set to "file". | Text | Optional |
| Response path | This is the path of the data object in which the response will be saved. | Data Object | Mandatory |
| Response header path | The path of the data object in which the response headers can be saved (text collection). | Data Object | Optional |
| Response status message path | The path of the data object in which the status message of the response can be saved. | Data Object | Optional |
| Cookie path (I/O) | The path of the data object that contains the cookies to be sent AND in which the received cookies (the Set-Cookie headers) are to be added. This maintains the full list of required cookies (e.g. can be used for round-trip multiple requests). | Data Object | Optional |
| Trace full request and response | Check this box to have the full request and response data output to debug tracing if debug tracing is enabled. | Checkbox | Mandatory |
| Connection Information | |||
|---|---|---|---|
| Host | This is the hostname of the web service to which to connect. | Text | Mandatory |
| Port | This is the port number of the web service to which to connect. | Text | Mandatory |
| Type | This is the connection type. | HTTP | HTTPS | Mandatory |
| Minimum TLS version | Specifies the minimal TLS version to accept on an HTTPS connection. | v1.2 | v1.1 | v1.0 | Optional |
| Maximum TLS version | Specifies the maximum TLS version to accept on an HTTPS connection. | v1.2 | v1.1 | v1.0 | Optional |
| Header Information | |||
| Method | This is the call method associated with the particular web service. | GET | POST | Mandatory |
| Path | This is the path of the web service call. | Text | Optional |
| Content type | This is the content type for the web service call. | Text | Optional |
| Charset | This is the character set for the web service call. | Text | Optional |
| Soap action | This is the SOAP action of the web service call. | Text | Optional |
| Http version | This is the version of the HTTP for the web service call. | Text | Optional |
| Maximum redirects | This is the maximum number of redirects the system should allow for the web service call. | Number | Optional |
| Read block size | This allows you to specify the chunk size in which the system reads the responses; the default is 8kB. You can use this to optimize the download speed, for example, to increase the value for large downloads. | Number | Optional |
| Custom headers | This is where the user enters any customized headers the system should add to the web service call. | Collection | Optional |
| Certificates | |||
| Request | This field is required when the method is set to "POST". It is the request that the system should send. | Text | Optional |
| Use certificate | This field is only available when the type is "HTTPS". It tells the system to verify certificates (see article Certificate verification for more information) provided by the remote end point. This option must also be checked when a client certificate needs to be passed for authentication. | Checkbox | Optional |
| Server certificate path | This field is only available when the "Use certificate" checkbox is checked. It is the file path for the local certificate store containing all valid server certificates. The certificate provided by the remote end point is validated against the certificate(s) in the configured file. This file needs to contain all the certificates in the certificate chain used by the presented remote end's certificate. When this field is left empty, the default certificate store is used (see article Certificate verification for more information). |
Text | Optional |
| Client authentication | This field is only available when the "Use certificate" checkbox is checked. It tells the system to enable or disable client authentication. | Checkbox | Optional |
| Client public certificate path | This field is only required when the "Use certificate" checkbox is checked. It is the file path of the public client certificate. | Text | Optional |
| Client private key path | This field is only required when the "Use certificate" checkbox is checked. It is the file path of the client's private certificate key. | Text | Optional |
| Verify hostname | This field is only available when the "Use certificate" checkbox is checked. It it tells the system to enable or disable hostname verification. | Checkbox | Optional |
| Hostname | This field is only required when the "Verify hostname" is checked. It is the hostname to be verified. Note: when the server certificate path is not set, then hostname verification is also disabled. |
Text | Optional |
| Synchronously/Asynchronously | |||
| Asynchronously | Yes: Call the webservice asynchronously. No: Call the webservice synchronously. |
Yes | No | Mandatory |
| Worker-handle | This is only required when "Asynchronously" is set to "Yes". It is the name of the worker handle to handle the asynchronous web service call. | Text | Optional |
| Generate detailed progress | Enable this option to allow the system to pass detailed progress steps during the asynchronous request. This is only available when asynchronously is set to Yes. Default: No. | Yes | No | Optional |
| Respond asynchronously | Enable this option to expose time-out and delay configuration options. Default: No. | Yes | No | Optional |
| Respond asynchronously timeout | This is the number of seconds a request waits until the system aborts it. Default: 600 seconds (10 minutes). | Number | Optional |
| Respond asynchronously delay | This is the number of seconds the system will wait before processing the next received chunk. Use this to throttle the chattiness of the asynchronous responses. | Number | Optional |
| Authorization | |||
| Authorization type | None: Do not use authorization. Basic: Use authorization by username and password. Bearer - pass-on token from external access provider: The access token is stored in the user-profile and obtained from authentication with an external access provider. Bearer - generated token from user profile for IdP client: Use the locally generated token from user_profile for a specific IdP. Bearer - generated token from user profile: Use the locally generated token from the user profile. Custom: Specify any other authorization protocol. |
None | Basic | Custom Text | Optional |
| Authorization | This allows you to define a custom authorization header. This is only enabled when you select Custom authorization type. | Text | Optional |
| Client ID | This is the specific client ID known by the IdP when you use the custom bearer token for a specific IdP. | Text | Optional |
| Username | This is only required when "Authorization" is set to "Basic". It is the username required for authorizing the connection. | Text | Optional |
| Password | This is only required when "Authorization" is set to "Basic". It is the password required for authorizing the connection. | Text | Optional |
| Ignore outbound whitelisting (Release 8.1+) |
Calls to other domains must normally be whitelisted by your administrator (see Outbound API Security) or the system configuration can be ignored by enabling this option. | On | Off | Optional |
Error Messages
| Error Message | Description |
| Unknown connect error | The host can be reached, but the socket on the server is not opened for receiving a connection. |
| Cannot connect | The server hostname is not correctly configured if HTTPS is used. |
| Host not found | The server hostname is not correctly configured if HTTP is used. |
| Error initializing locations | The path to HTTPS server certificate is not valid or the certificates in that configured path are not valid. |
| Unable to get local issuer certificate | The server certificate cannot be validated. Please check whether all certificates in the server certificate chain are saved in the configured certificate file. |
| Could not set client certificate key | The configured client certificate private key is corrupt or the private key does not belong to the configured client certificate. |
| Failed to set client certificate | The configured client certificate is corrupt. |
| HTTP Error 401.2 - Unauthorized | You are not authorized to view this page due to invalid authentication headers. This could be caused because an invalid client certificate was used. |
| HTTP Error 403.16 - Forbidden | Your client certificate is either not trusted or is invalid. |
| HTTP Error 403.17 - Forbidden | Your client certificate has expired or is not yet valid. |
| Failed to Connect; error=5; verification result code=0; description=ok | The configured TLS version is incorrect; for example, TLS 1.0 is configured but you are connecting to a webservice that accepts only TLS 1.2. |
Extended Error Logging
It is possible to enable extended error logging for web services when you have access to your LogicNets runtime installation/server access.
- Open or create a configuration file, for example, c:\logicnets\dat\bnt\yourcompany\settings.cfg.
- Add a setting called 'log_webservice_calls' in the "_session" section. Assign value = 1.
_session = { log_webservice_calls = 1 } - Run your application.
- Check the log files in c:\logicnets\dat\log\.
host: test port: 8080 TLS version: 1.2 Connection type: HTTP server validation certificate file: nil client identification certificate file: nil client identification private key file: nil ------------------- Full request ------------------- POST /examplecall HTTP/1.1 Host: test Content-type: text/plain; charset="utf-8" Content-length: 0 SOAPAction: "Action" ------------------- End ------------------- >> Starting call Error: "cannot connect: host not found" ------------------- Response ------------------- nil ------------------- End -------------------
Example
For several examples of using the call webservice part, download the following sample project in your workspace.
Reply
Content aside
- 5 yrs agoLast active
- 172Views
-
3
Following