This connector is used to send HTTP requests and retrieve the response in one of the following formats: raw text, document (JSON) or binary (file).

• It enables exchanges with third-party applications providing REST Web services, to retrieve remote binary files or, more generally, to communicate with HTTP servers.
• This connector is commonly used in Self Help Connection Package templates.

Notes

      See General remarks on standard connectors

• The methods available are the standard HTTP methods: GET (read), POST (write), PUT / PATCH (update), DELETE (delete).

General connector configuration

The general configuration is common to all connector methods.

• You can override it in the procedures.
• The (URL) parameter is the only mandatory parameter.
   

URL: Web service URL.

Authentication: HTTP authentication method used by the Web service. The parameters to be specified will vary depending on the authentication method.

• BASIC: Specify the Login and Password fields.

• DIGEST: Specify the Login and Password fields.

• BASICPRE (BASIC preemptive): Authentication credentials will be sent before an explicit server request is made. Note: This authentication method is used for sending requests to Service Manager.
  • Specify the Login and Password fields.

• NTLM: Specify the Login field in the following format, DOMAIN\\\\ID.

• OAuth: There are two authentication methods via OAuth.
  • client_credential: This authentication method requires you to specify the URL for retrieving tokens.
    • Specify the Authentication field in the following format, oAuth:<URL for retrieving tokens>.
    • Specify the Login and Password fields.
  • Salesforce: This authentication method requires you to specify the client ID and client secret (optional).
    • Specify the Authentication field in the following format,  SFDC:<auth_url>:<client_id>[:<client_secret>].
    • Specify the Login field and the client ID that should be found at the end of the security token.
       

Login: Login used by the HTTP authentication, to be specified depending on the authentication method.

Password: Password used by the HTTP authentication, to be specified depending on the authentication method.

Result file name: This parameter is used only if the response is a binary file.

Proxy: URL of the HTTP proxy, including authentication.

Input parameters common to all connector methods

Query string parameters: List of key-value pairs in cells sent in the URL in the query string variable found after the question mark (<url>?query string).

HTTP Headers: List of key-value pairs sent with the request as additional HTTP headers.

Description of connector methods

GET Request

The GET Request method is used to read data.  See the use case

• The result is interpreted based on the HTTP response headers.

Additional input parameters for the method

force JSON: When this box is checked, this indicates that the response is expected in JSON format and that it should be interpreted as such, even if the content-type response header indicates otherwise.

• This option is useful because some Web services do not load headers correctly.

POST Request, PATCH Request and PUT Request

The POST Request method is used to send data in urlEncoded format like Web forms, or to send the contents of a file (text or binary).

The PUT Request method works in the same way as POST Request with regard to the connector, but not with all services. 

The PATCH Request method works in the same way as POST Request with regard to the connector, but not with all services. 

Additional input parameters for methods

Form data to send: Data (key-value pairs) sent in the body of the method in urlEncoded format.

• If the parameter is unspecified, the contents of the first file present is sent in the connector context. This may be a file present in the step, e.g. file attachment, or a file placed by another connector in the same step.

POST String Request, PATCH String Request and PUT String Request

The POST String Request method is used to send character string data.

The PUT String Request method works in the same way as POST String Request with regard to the connector, but not with all services. 

The PATCH String Request method works in the same way as POST String Request with regard to the connector, but not with all services. 

Additional input parameters for methods

Data to POST: Data sent in the body of the method.

DELETE Request

The DELETE Request method is used to delete data.

Result and errors returned by the connector

Result

• If the HTTP call is successful, the connector will return the result output parameter even if the server returns an error, e.g. HTTP status 500, 404, etc.
  • The interpretation of the parameter depends on the value of the content-type HTTP response header.
  • If the content-type HTTP header indicates that the response is in JSON, text or XML format, or if the force JSON parameter is selected in the GET Request method, the parameter will contain an object with the following variables:
    • result.body: Body of the response, i.e. text or document in JSON format.
    • result.json: Boolean indicating if the result.body variable is a complex JSON object. If this is the case, its elements will be directly accessible.
    • result.status: HTTP status, e.g. 200 = "OK", 404 = "Not Found", etc.
    • result.encoding: Encoding of the result.body variable.
    • All other HTTP response headers, e.g. content-type, etc.

• If the HTTP call fails, the connector will return the response in text format.
  • The values of the content-type HTTP header indicated as text are as follows: application/json, application/x-javascript, text/javascript, text/x-javascript and text/x-json.

• If the content-type HTTP header indicates that the response is in text or XML format, the response will be returned in raw text directly in the result.body variable.
• In other cases (including when the content-type HTTP header is missing or empty), the response will be returned in a file loaded in the context of the connector, in the Result file name variable if specified. If the variable is unspecified, it will be returned in the URL path.

• If the response is a binary file, the file is loaded in the context of the step, in the name specified in the parameter and is available to other connectors, such as the Email sending connector.

Error

• If the HTTP call fails because of an error with the connector or with the connection, the connector will return a description of the error in the error output parameter.

• If the HTTP call is successful but a status with an error code is issued, e.g. 500 or 404, the connector will return the result output parameter.

Use case

See detailed step by step on Self Help portal

GET Request method

The procedure enables you to retrieve information on a ticket in Service Manager using its ID by calling the GET Request connector method and the View a ticket method of the Service Manager REST API.

      See the detailed procedure

List of files to download

• PDF file for the use case

• Sample project