Call Endpoint Module

    Introduction

    The Call Endpoint module was introduced to enable apps, running on a tapio connected machine, to call other tapio applications. Instead of making REST calls directly from an app running on the machine, we wanted to have the CloudConnector as a proxy, to be our single point of contact with the internet. This has several advantages, for example the use of the existing authentication of the CloudConnector against the tapio core platform. We therefore created a new module within the CloudConnector, called the Call Endpoint Module. It provides an OPC UA interface, which accepts a call and forwards it to the requested resource.

    Make a call

    To call another tapio resource through the CloudConnector, you first need to adapt the CloudConnector configuration to provide at least one CallEndpointIdModule, which looks like this:

    <Module xsi:type="CallEndpointIdModule">
      <Id>Endpoints</Id>
      <Endpoints>
        <Endpoint>
          <TapioMachineId>23123123</TapioMachineId>
          <NodeId>FirstMachine</NodeId>
        </Endpoint>
        <Endpoint>
          <TapioMachineId>123123123</TapioMachineId>
          <NodeId></NodeId> <!-- optional node id name -->
        </Endpoint>
      </Endpoints>
    </Module>

    Tip: Configuring a NodeId.

    The NodeId xml node defines the NodeId within OPC UA, that will accept a synchronous OPC UA call containing information about the tapio API to call.

    The actual OPC UA call will look like this:

    // We will provide a working C# example in the near future.

    OPC UA Method Call Parameters

    The following parameters can be defined within the OPC UA Call:

    Parameter Type Description
    ResourceId String Unique Identifier (Guid) of the resource, which should be called
    RequestType String HTTP Method of the call (e.g. GET, POST, PUT, DELETE, HEAD, PATCH)
    PathAndParameters String Relative path to be called on the resource (e.g. api/path?search=12)
    Headers StringArray Array of strings in the form of "key:value" containing the HTTP request headers
    Body ByteArray Optional request content. Content-Length Header will be set automatically

    You may have noticed, that we're not defining an exact URL to call, just a relative path. We will receive the absolute URL of the endpoint we want to call from GlobalDiscoveryService, since our original OPC UA call is forwarded to Field API and GlobalDiscoveryService.

    The Field API will concat the endpoint we got from GlobalDiscoveryService with the parameters it got from the OPC UA call and do the actual request on the resource. It will also add additional headers, for example authentication headers that might be necessary to call the resource. Field API will then return the call back to the CloudConnector, which maps the call back to OPC UA format with the following output parameters:

    Parameter Type Description
    StatusCode Integer HTTP Status Code
    StatusDescription String
    Headers StringArray Array of strings in the form of "key:value" containing the HTTP response headers
    Body ByteArray The content of the response

    Register external Endpoint Resource

    To enable a resource to be called through the Call Endpoint Module, we first need to apply some settings within tapio SelfService.

    Since there is currently no UI available, so you can adjust the settings yourself, please provide the following information via email to developer@tapio.one:

    • Application that calls the endpoint (Application Name in tapio SelfService)
    • Json Structure for endpoint Connection:
    {
      "url": "url of the endpoint",
      "authenticationType": "header",
      "authentication": {
        // depends on the authenticationType
        // if authenticationType === header
        "headers": {
          "user-provided-header-name": "shared-secret-value",
          "multiple-headers": "are supported"
        }
      }
    }

    You will then receive a Guid from us - the ResourceId of your Endpoint - that you need to pass in the OPC UA call, since we're not passing actual endpoint URLs as described in the OPC UA Call parameters section.

    The endpoint does receive two additional HTTP headers from the tapio system:

    Header Description
    Tapio-Tmid The tapio machine id which calls the endpoint
    Tapio-Endpoint-Id The endpoint which is used for this call