Connecting to Web URLs

A Web Connection can be used by the [Web.Query:] macro in ReportMagic to:

• Set a base URL, so that the url parameter in the macro is interpreted as a relative one
• Use Authentication without adding credentials in a report

To set up a Web Connection:

1. From the Admin menu, click Connections.
2. Click the Create button.
3. Choose the type of Connection as Web.
4. Set a base URL by adding this into the Configuration section:
   {
       "BaseUrl" : "<http|https://base-url-here>"
   }
5. Use Basic Authentication as follows:
• Set the Username and Password in the standard connection fields
• Add the following to the Configuration section:
  
  {
      "AuthType" : "Basic"
  }
• You can use the BaseUrl in combination
  {
      "BaseUrl" : "<http|https://base-url-here>",
      "AuthType" : "Basic"
  }
6. You can also set any number of default HTTP headers to send with the request, by adding them to the Configuration section, for example:
   {

       "DefaultHeaders": [

           {

               "Key": "My Header 1",

               "Value": "Some value"

           },

           {

               "Key": "My Header 2",

               "Value": Some value"

           },

       ]

   }

OAuth 2.0 Authentication

Currently supported options are:

• Grant Type: password credentials or client credentials
• Client Authentication: Send client credentials in body

You may also specify a client ID, client secret, scope, as well as the name of the token (the name is then returned by the server in its response). On the Connection, set these fields:

For the PasswordCredentials Grant Type:

1. URL: the authentication endpoint
2. User Name: the username
3. Password: the password

For the ClientCredentials Grant Type:

1. URL: the authentication endpoint
2. User Name: not used
3. Password: not used

In the Connection's Configuration section, use the following (note "BaseUrl" is optional), and TokenName can be set to anything:

Note: when using the 'CustomAuthHeader', the authentication token is not sent using the "Bearer" authentication header, but instead in a custom header with the name specified.

You may also, optionally, use an NCalc expression to determine the value of this header, by using the CustomAuthHeaderValueExpression configuration parameter. This parameter can be any NCalc expression, but the token 'authToken' can be used as an input to the expression.

For instance, to just use the token on it's own, specify a value of just authToken, i.e.

"CustomAuthHeaderValueExpression": "authToken"

But you could use a more complex expression, e.g.

"CustomAuthHeaderValueExpression": "'abc' + authToken"

An example complete OAuth2 configuration is shown below:

{
    "AuthType" : "Oauth2",
    "BaseUrl" : "https://myurl/api/devices/",
    "TokenName" : "AccessToken",
    "GrantType" : "ClientCredentials",
    "ClientAuthType" : "SendClientCredentialsInBody",
    "Scope" : "api://xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/.default",
    "ClientID" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ClientSecret" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "CustomAuthHeaderName" : "X-Backend-Token",
    "CustomAuthHeaderValueExpression": "authToken",
}

Manually Create a Macro Parameter Default

Unlike most other Connection types, a Macro Parameter Default is NOT automatically created for this new connection, meaning that all [Web.Query:] macros will only use it if you do one of the following:

• Specify [Web.Query: connectionName=XYZ]
• Manually add a Macro Parameter Default
• Use the Settings macro to specify it