Functions: Http Request

The HTTP Request functions are used with the WrapConnector API to send HTTP requests from a wrap to a remote system.

The WrapConnector API allows a wrap to communicate with remote systems. There are two flavors of the HTTP Request functions, one to initiate processing (POST/PUT) and one to request data (GET). As an example, if a wrap is remotely controlling a tool like a torque wrench using the WrapConnector API, the process is done in two steps:

  1. The wrap POSTs information to the wrench instructing it on what to do, like the number of bolts to tighten and the minimum torque to apply.
  2. The wrap GETs the result from the tool after tightening is complete, to save in the database exactly how much torque was used for each bolt.

Result data about the performed operation can optionally be returned by both POST, PUT and GET in the form of a JSON structure.

ExcelWraps provides a set of ValueAt functions to parse JSON data.

Example of POST

A POST is requested with the HttpPostRequest function:

=HTTPPOSTREQUEST(type, button-text, id, optional-json-as-string, range-of-args)

The function syntax is described in detail in the Function Reference below.

An example of POST:

TBD

A POST or PUT can also send a device- and operation-specific JSON structure with the details of the requested operation.

Example of GET

A GET is requested with the HttpGetRequest function:

=HTTPGETREQUEST(type, button-text, id, range-of-args)

The function syntax is described in detail in the Function Reference below.

An example of GET:

=HTTPGETREQUEST(=if(A1<>0,1,0),B1:B4)

where

  • B1: “Program wrench”
  • B2: “436-463732-ghsfd-67”
  • B3: =A1
  • B4: =A2

A GET request does not send a JSON structure.

Example Using GET with another wrapsite

If you have the appropriate access token, you can read data in wrapsite B from wrapsite A with a link like

https://B.live.excelwraps.com/api/...{1}...

Example: a MyWraps2 report

TBD

The stored value from the previous execution

The result from the previous execution of an HTTP request is stored in the wrap and used until we perform the operation again and get a new value.

The stored value is used for:

  • Frozen wraps.
    If the wrap is frozen, the HTTP request is not performed, and the last stored value is permanent.
  • Not enough privileges.
    If a user doesn’t have one of the roles required for the HTTP request, the operation is not performed and the last stored value is retained in the wrap.

Function reference

Example

=HTTPGETREQUEST(=if(A1<>0,1,0),B1:B4)

In the example above, a HttpGetRequest function is used to request information from a remote system. The requested data is returned in the form of a JSON structure that can be parsed with a ValueAt function.

The first parameter disables the operation if there is no request ID. The second parameter designates a cell range with additional parameters.

Format and parameters

=HTTPPOSTREQUESTtype, button-text, id, optional-json-as-string, range-of-args)
=HTTPPUTREQUEST(type, button-text, id, optional-json-as-string, range-of-args)
=HTTPGETREQUEST(type, button-text, id, range-of-args)

Type

  • 0 = disabled, no HTTP request done, and no button is shown. Change to non-0, when enough args have values. The previous result value is kept (taken when type>0)
  • 1 = by button

Button-text

The text on the button. A button only appears when type=1. It should be updatable by Excel, i.e. a cell reference is required, not a static string.

Id

The id of the http request on the server. The number of args must match.

optional-json-as-string

If a POST or PUT requires additional data to be sent to the remote system, a request-specific JSON structure is provided in the function call. The server will validate the JSON before making the POST or PUT request, and if it doesn’t accept the JSON you will get an HTTP 400 Bad Request error.

range-of-args

A cell range with zero to ten arguments for the placeholders in the query string for POST and PUT operations. Arguments are inserted sequentially, so if there are two arguments in B1:B2, the {1} placeholder in the link will be replaced by the value in cell B1 and the {2} placeholder will be replaced by the value in cell B2.

A placeholder can be used more than once in the link.

  • For numbers, scientific or exponential notation like “1e-10” is not supported.
  • Booleans are inserted as true or false using lowercase.
  • Strings are automatically URL-encoded by the server and inserted with appropriate string delimiters.
  • Empty arguments are not permitted, e.g. you cannot use “&source={1}&data={2}” in the link and then turn this into “&source=&data={2}” using an empty cell for the first argument.

If range-of-args does not have the same number of cells as the number of placeholders you will get an HTTP 400 Bad Request error.

Authorization tokens

The WrapConnector API uses authorization tokens provided by the remote system. These tokens are stored with the WrapConnector definition.

Result

All HTTP request functions return the HTTP status for the operation, normally 200, and optionally a JSON structure. This information is also stored in the audit trail.

If the user does not have at least one of the roles required for the WrapConnector, you will get an HTTP 401 Not Authorized error.

If none of the provided tokens are accepted by the remote system, you will get an HTTP 401 Not Authorized error.