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.
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.
HTTP method	String	No	The following methods have been implemented: GET, POST, PUT, HEAD, DELETE. If not specified, POST is used by default.
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.
Timeout	Long	No	A timeout for requests in milliseconds.
URL	String	Yes	The URL you want to send the request to. For more information, see URL encoding below.
Authentication options
Authentication type	String	Yes	Supported values: none, basic, basic_direct, basic_bearer, oauth and aws_signature. For more information, see Authentication options below.
Authentication user	String	No	User name. If Authentication type is set to aws_signature this field is renamed Amazon Key ID and is required.
Authentication password	String	No	Password. If using basic_bearer, use this field to send the bearer token. If Authentication type is set to aws_signature this field is renamed Amazon Secret Key and is required.
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.
Region	String	No	The AWS region. Required when the Authentication type is set to aws_signature.
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. You can use an Authorization of webservice case to generate an OAuth 2.0 access token, or implement your own solution to generate a bearer token.
• oauth: Requests are made with an OAuth 2.0 access token, which should be generated via an Authorization of webservice case. Populate the Authorization case field with the Authorization of webservice case ID in order to use the access token to make the request. For more information, see Authorization with OAuth 2.0 below.
• aws-signature: Requests are made with AWS Signature Version 4 (SigV4). This is designed for making requests to an AWS Lambda function (exposed either using a function URL or a web API using Amazon API Gateway). The Amazon Key ID and Secret Key must be supplied to authenticate the request. This authentication option should not be used in conjunction with the Authorization of webservice system service.

Authorization with OAuth 2.0

You can authorize requests to an external web service or API using OAuth 2.0. Currently, only the Client Credentials flow is supported. 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 OAuth 2.0 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 either basic_bearer or oauth.
  • 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 of the HTTP call	String	No	Authentication mechanism used to send the request to the protected resource (i.e. the external web service, API, or web endpoint). Supported values: none, basic, basic_direct, basic_bearer, oauth and aws_signature. For more information, see Authentication options above.
Authentication type of the authorization call	String	No	Authentication mechanism used to send the request to the authorization server. Supported values: none, basic, basic_direct, basic_bearer, and oauth. For more information, see Authentication options above.
Authorization user / Client ID	String	No	User name or ID used to authenticate the request to the authorization server.
Authorization password / Client secret	String	No	Password or secret used to authenticate the request to the authorization server.
Grant type	String	No	Supported values: clientCredentials. This option is not applicable when the Authentication type of the HTTP call is basic or basic_direct.
Scope	String	No	The level of access you want to request from the protected resource. To request a specific scope, enter a value as defined in the protected resource's specification. This option is not applicable when the Authentication type of the HTTP call is basic or basic_direct.
Client authentication method	String	No	The method used to send the client ID and secret (or user name a and password) to authenticate the request to the authorization server. Supported values: basic_auth_header or client_credentials_body. If client_credentials_body is selected, the values from the Client ID and Client Secret fields are added to the message body automatically. This option is not applicable when the Authentication type of the HTTP call is basic or basic_direct.
Custom body	Boolean	No	Set to true to be able to edit the body of the request before it is sent to the authorization server.
Body	String	No	The body of the request. This option is not applicable when the Authentication type of the HTTP call is basic or basic_direct.
Headers	JSON	No	Any headers you want to include.
URL	String	Yes	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
    }
}