HTTP call

Make calls to an external web service, API, or web endpoint. You can then use the response in another activity or map the data to another case so that you can display it in your application. You can download this system service from Grexx Marketplace.

Tip:

If you need to make multiple web service calls as part of a process, 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 HTTP call.

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. For more information, see URL encoding below.
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. For information about sending multiple values, see Multipart/form data below.
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. For more information, see Authentication options below.
Authentication user	String	No	User name.
Authentication password	String	No	Password. If using basic_bearer, use this field to send the bearer token.
Authorization case	Case ID	No	The case ID of an Authorization of webservice case. When this option is used, the Authentication password is populated automatically with the OAuth 2.0 access token. For more information, see Authorization with OAuth 2.0 below.
Client certificate options
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.

Tip:

This system service includes multiple casetypes to enable authentication and authorization features. To make a call to a web service with either no authentication or basic authentication, you only need to create a new HTTP call case (using the inputs listed above).

Output

Outputs are added to the Result form when the HTTP call 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.

Authentication options

When you create a new HTTP call case, you must specify the type of authentication you want to use when making the request to the external service:

• none: No authentication credentials supplied or required.
• basic: Requests are made to the external service without credentials. If the server responds with a request for credentials, a second request is made with the credentials provided on the form. The credentials are encoded in base-64 format. This option is not secure and should not be used to access sensitive data.
• basic_direct: Requests are made to the external service with credentials encoded in base-64 format (skipping the challenge/response step of the basic option). This option is not secure and should not be used to access sensitive data.
• basic_bearer: Requests are made with a bearer token in the authentication header. Select this option if you want to use OAuth 2.0, JSON Web Tokens, or similar.

Authorization with OAuth 2.0

You can authorize requests to an external web service or API using OAuth 2.0. The system service includes functionality to request access tokens from an authorization server of your choice and refreshes tokens automatically.

To use this functionality, you must configure both the Authorization of webservice and HTTP call casetypes:

• Authorization of webservice: This makes a request to the authorization service for an access token. Use the Start Authorization of webservice form to create a new case of this type for each authorization request. Specify the URL of the authorization server you want to use and the credentials as described below. You can then include the case ID in a HTTP call case instead of providing credentials.
• HTTP call: This makes a request to an external web service, API, or web endpoint using the OAuth 2.0 protocol. Use the Start HTTP call form to create a new case of this type for each call to an external service. Populate the start form as described above, but note the following:
  • Set the Authentication type to basic_bearer.
  • Map the case ID of the relevant Authorization of webservice case into the Authorization Case ID field.
  • Leave the Authentication user and Authentication password fields empty. The Authentication password is populated with the access token from the Authorization of webservice case automatically.

Authorization of webservice inputs

Use a casetype activity to add inputs to the Start Authorization of webservice form. Once you have created an Authorization of webservice case, you can include the case ID when creating a new HTTP call case.

Attribute	Data type	Mandatory?	Description
Name	String	No	A name to identify the authorization request.
Authentication type	String	No	Authentication mechanism used to send the request to the authorization server. Supported values: none, basic, basic_direct, and basic_bearer. For more information, see Authentication options above.
Authorization user / Client ID	String	No	User name or ID used for authentication.
Authorization password / Client Secret	String	No	Password or secret used for authentication.
Body	String	No	The body of the request.
Headers	JSON	No	Any headers you want to include.
URL	String	No	The URL of the authorization server that will authenticate the request and issue the access token.

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

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
    }
}