Downloading Files to a Machine

Introduction

tapio's TapioCore Web API enables:

• downloading a file from an external source to the machine.
• request the state of the download.

This way, large files can be transferred to the machine (like cutting plans) and at any moment it is possible to know if downloading is started or not and when the transfer is finished.

General

To be able to make requests to the Core TapioCore Web API, you first need to configure your CloudConnector instance and register a tapio application and assign machines to the application. You won't be able to start download for machines that are not assigned to your application or if machine is in "offline" state.
Authentication in TapioCore Web API is done via Azure AD B2C. See our guide on authentication for more details. Also do not modify files inside {dataDirectory}/persistentStorage/.

The persistentStorage-directory is used internally to persist the state of file transfers during critical phases.

CloudConnector Configuration

Add a module configuration section to your XML configuration file:

Example

<Module xsi:type="FileTransferModuleConfig">
  <Id>FileTransferModule</Id>
  <ApplicationUri>urn:Tapio:ServerName</ApplicationUri> <!-- => former "LdsName" -->
  <OpcServer>opc.tcp://tapio.one:17636/MyServer/</OpcServer>
  <RemoteLds>opc.tcp://tapio.one/MyServer/</RemoteLds>
  <OpcUaMaxConnectTime>00:01</OpcUaMaxConnectTime> <!-- => one minute -->
  <Authentication xsi:type="AuthenticationUserName">
    <UserName>thelegend27</UserName>
    <Password>somePassword!</Password>
  </Authentication>
  <Downloads>
    <Download>
      <Id>3dModel</Id>
      <NodeId>MyServer.TheTemporaryFileTransferTypeNode</NodeId>
    </Download>
    <Download>
      <Id>CustomerOrder</Id>
      <NodeId>MyServer.OtherTemporaryFileTransferTypeNode</NodeId> // different versions
    </Download>
  </Downloads>
</Module>

Note: Either set the ApplicationUri tag to connect via local discovery service or set the OpcServer tag to establish a direct connection. Additionally you can use a remote discovery service using the RemoteLds tag.

Note: If you want to send files to multiple OPC UA servers you have to configure multiple file transfer modules.

File transfer module configuration model

Property	Type	Description
Id	string	Unique identifier of the module. Simultaneously used as the OPC UA server identifier.
ApplicationUri	string	OPC UA server address to connect using a local discovery service.
OpcServer	string	OPC UA server address to connect directly.
RemoteLds	string	OPC UA server address to connect using a remote discovery service.
OpcUaMaxConnectTime	string	Maximum time span the OPC UA client takes to try to establish a connection. Formatted like a C# TimeSpan.
Authentication	-	Authentication configuration.
Downloads	-	List of Download items.

Note: If you want to connect using an ApplicationUri the XML tag OpcServer has to be empty.

Download configuration model

Property	Type	Description
Id	string	Unique identifier of the download.
NodeId	string	The NodeId of the TemporaryFileTransferType-node on the destination OPC UA server. Supported formats.

WebAPI Interaction

Downloading a file is done asynchronously. You need to enqueue a download request, which returns a correlation id. You can then use this correlation id to query the status of the download and wait for it to finish.

Use the ResourceId https://tapiousers.onmicrosoft.com/CoreApi for the token request otherwise you get an Unauthorized.

Enqueue a Request

You enqueue a download request using POST https://core.tapio.one/api/machines/<tmid>/downloads/. This call will return an http response with return code 202 if the request was successful, as well as a response body defined here. Because the call also immediately tries to trigger the download, the call may take a few seconds, especially if the device is currently offline.

POST https://core.tapio.one/api/machines/<tmid>/downloads/

Use Content-Type: application/json;charset=UTF-8 in your request headers Use the ResourceId https://tapiousers.onmicrosoft.com/CoreApi for the token request otherwise you get an Unauthorized.

Request

{
  "serverId": "UniqueId01",
  "id": "Download-Id",
  "downloadUrl": "https://url-to-file-download_incl-sas-token",
  "ttl": "P2D",
  "commandType": "TemporaryFileTransferType.GenerateFileForWrite",
  "inArguments":
  {
    "generateOptions":
    {
      "valueType": "string",
      "value": "- user specific data - will be passed into the argument -"
    }
  },
  "responseTimeOut" : "00:00:30",
  "connectionTimeOut" : "00:00:30"
}

Request-Properties

Property	Type	Required	Default value	Description
tmid	string (guid)	yes		tapio machine id of the machine you want to download to
serverId	string	yes		Server Id of the OPC UA server as configured (TODO Add link)
id	string	yes		Id of the actual target where the file will be downloaded to
downloadUrl	string (URL)	yes		URL of the file to download, including any authentication parameters if required
ttl	string (ISO8601 Timespan)	yes		Time to life - time after which CloudConnector no longer tries to download the file
commandType	string	yes		Must be "TemporaryFileTransferType.GenerateFileForWrite"
inArguments	InArguments-Object	no		See below
responseTimeOut	string (TimeSpan)	no	"00:05:00"	Overall timeout for scheduling jobs
connectionTimeOut	string( TimeSpan)	no	"00:00:15"	Timeout for the connection

InArguments-Object

Property	Type	Description
generateOptions	GenerateOptions-Object	See below

GenerateOptions-Object

Property	Type	Description
valueType	string	must be "string"
value	string	Options that need to be passed when creating download target

Enqueue Download Response

{
    "correlationId": "d4c45c5f-a234-40e8-b82e-81b4869b6caa"
}

Set connection-timeout and response-timeout

You can override the default response timeout for scheduling jobs and the connection timeout for each command.
The timeouts can be set independently. If no timeouts are set, the default values are used.

Be aware, that the connection timeout needs to be smaller than the response timeout. Also both values need to be set in a time range from 00:00:05 - 00:05:00

Response-Object

Property	Type	Description
correlationId	string (guid)	Correlation id used to query download state

Query State

GET https://core.tapio.one/api/machines/<tmid>/downloads/<correlationId>

Use the ResourceId https://tapiousers.onmicrosoft.com/CoreApi for the token request otherwise you get an Unauthorized.

Query State Response

{
    "enqueueDate": "2019-01-01T13:00:00Z",
    "status": "Ok",
    "statusDescription": "",
    "lastUpdateDate": "2019-01-01T13:05:00Z"
}

Property	Type	Description
enqueueDate	string (ISO8601 Date)	Date when the request was enqueued
status	string	One of Ok Pending Failed Running
statusDescription	string	In case of Failed this includes the actual error message.
lastUpdateDate	string (ISO8601 Date)	Date of the last status change

Value	Description
Ok	File download was successful
Pending	File download is enqueued but has not yet started
Failed	File download was unsuccessful
Running	File download was started

Return Codes

Possible return status values: 200, 202,400, 401, 403 , 404

Http Status Code	Description
200	Execution of this request was successful.
202	Execution of this request was successful, query the result using the returned correlation id.
400	Execution of this request failed, because something went wrong. Check the response.
401	Execution of this request failed, because application is not authorized. Check the response.
403	Execution of this request is forbidden. Check the response.
404	Execution of this request is not done because something does not exist.

Ok

If you are trying to download file for an application which is authorized for commanding, this call will return an http response with return code 200 (ok), and appropriate body e.g. see: Enqueue Download Response.

If you are trying to to get download state for an application which is authorized for commanding, this call will return an http response with return code 200 (ok), and appropriate body e.g. see: Query State Response.

Forbidden

If you are trying to download file or to get download status for an application which is not authorized for commanding, this call will return an http response with return code 403 (forbidden), and appropriate message: Application is known, but not authorized for this action.

Not found

An http response with return code 404 (not found) and appropriate message is returned in cases:

• If you are trying to download file using invalid tapio machine id (e.g. id not exist).
• If you are trying to get download status using invalid tapio machine (e.g. id not exist).
• If you are trying to get download status using invalid correlation id.

Bad Request

An http response with return code 400 (bad request) and appropriate message is returned in cases:

• If you are trying to enqueue download for the machine which is offline (Message: "Machine not reachable").
• If you are trying to enqueue download providing no body in request or providing invalid body.
• If you are trying to enqueue download providing invalid value for any parameter in request body.
• If the passed timeout values have the wrong format or are smaller then 00:00:05 or bigger then 00:05:00.
• If the connection timout is bigger than the response timeout.

Unauthorized

An http response with return code 401 (unauthorized) and appropriate message is returned in cases:

• If you do not send authorization header in request or can't be parsed.
• If the header is past it's expiration date.

If you have any further questions regarding our Core Web API, don't hesitate to contact developer@tapio.one

OPC UA Server Implementation Hints

We implemented OPC UA interaction according to the official OPC UA specification.

Therefore we expect that calling the GenerateFileForWrite() method on a TemporaryFileTransferType node returns a fully implemented FileType node (as specified in the OPC UA Specification - Part 5, Annex C).

You might have to extend existing OPC UA implementations in order to be able to support file transfer due to not being able to set a file handle on vanilla FileType nodes manually.