Consume web service

Make calls to an external web service, API, or web endpoint.

Two versions of this system services are available to download from Grexx Marketplace:

• System service consume web service (ESS) - latest version containing additional features.
• System service consume web service - legacy version

Tip:

If you are using the ESS version of this system service, you can configure activities to make multiple requests in parallel in order to improve performance.

Input

Use a casetype activity to add inputs to the Start Systemservice consume webservice form.

Attribute	Data type	Mandatory?	Description
Body	String	No	The body of the request.
URL	String	Yes	The URL you want to send the request to.
HTTP method	String	No	The following methods have been implemented: GET, POST, PUT, HEAD, DELETE. If not specified, POST is used by default.
Time-out	Long	No	A timeout for requests in milliseconds.
Content type	String	No	MIME type.
Headers	JSON	No	Any headers you want to include.
Ignore errors	Boolean	No	If the HTML status is below 200 or above 300, it may or may not throw an error. This error handling only applies to HTTP errors. All non-HTTP-related errors are returned regardless of the value of this boolean.
Authentication options
Authentication type	String	Yes	Supported values: none, basic, basic_direct, and basic_bearer.
Authentication user	String	No	User name.
Authentication password	String	No	Password. If using basic_bearer, use this field to send the bearer token.
Client certificate options (ESS version only)
Client certificate	File	No	The certificate used to validate the client's identity. This includes PKCS#12 certificates or certificates of a certificate/key pair.
Client certificate key	File	No	The "private key" with which the sent data is encrypted/decrypted.
Client certificate passphrase	String	No	The passphrase/password of the certificates.

Output

Outputs are added to the Result Systemservice consume webservice form when the Systemservice consume webservice case is closed.

Attribute	Data type	Mandatory?	Description
Return code	Integer	No	HTTP status code.
Return headers	String	No	Headers.
Return body	String	No	The result of the call.

URL encoding

You are responsible for encoding your URL correctly. The system service simply converts any remaining spaces in your path to %20 and any remaining spaces in the query section to +.

For a brief explanation of URL encoding, see https://www.urlencoder.io/learn/.

You can use the util.urlEncode template function to convert all required characters to percent-encoding.

Note:

Do not use this template function for your entire URL. The function is designed to encode specific parts of your URL, such as the variables included in the final query. Make sure that the ?, & and = from the query and the / from the path are not included in the function.

Multipart/form data

Note:

This feature is only available with the System service consume web service (ESS) product.

Multipart/form data is normally used to send a combination of information and/or files to a server from a browser. You may need this for a specific connection.

To send your data as multipart/form data:

• Set the content-type to multipart/form-data.
• Send a JSON with key/value pairs as body. Each key is treated as a part for the multipart. Examples are provided below.

JSON for values

{
    "name": "William",
    "city": "Amsterdam"
}

JSON for files

To send files, your value must be a JSON with at least a filename and a raw or base64 field. Below you can see some examples.

{
    "name": "In addition to a file, you can also send another value here."
    "attachment-as-base64": {
        "filename": "file.pdf",
        "base64": "aGVsbG8gd29ybGQ="
    },
    "attachment-as-raw": {
        "filename": "file.xml",
        "raw": "<root>Hello world!</root>"
    },
    "attachment-with-options": {
        "filename": "file.xml",
        "base64": "aGVsbG8gd29ybGQ=",
        "filepath": "xml-files/index.xml",
        "contentType": "application/xml",
        "knownLength": 11
    }
}