Generic Entity Usage Example - Log File

In the following example, we are going to create a log file generic entity and attach it to a device.
We are going to cover the following steps:

1. Creating a Generic Entity template
2. Obtaining the template unique ID
3. Obtaining the organization unique ID
4. Uploading a file to BioT
5. Attaching a file to a new generic entity instance
6. Downloading the file from the manufacturer portal

Creating a Generic Entity template

Follow the steps described here to create a new generic entity.
For this example, we will name it Device Log.
Add a File attribute to it and name it TXT Log File.
Set the max file size to 10 MB.

Now, add another attribute of type Entity. Set it to type Device and Any.
Name it Log File Ownerand in the Referenced side attribute... enter Logs
This will allow us to attach many log files to a single device entity.

Save the new template.

Obtaining the template unique ID

To obtain the template unique ID, make the following API call:

GET https://your-biot-domain.com/settings/v1/templates/minimized
With the encoded body:

{
  "filter": {
    "name": {
      "eq": "device_log"
    }
  }
}

To produce:
https://your-biot-domain.com/settings/v1/templates/minimized?searchRequest=%7B%0A%20%20%22filter%22%3A%20%7B%0A%20%20%20%20%22name%22%3A%20%7B%0A%20%20%20%20%20%20%0A%20%20%20%20%20%20%22eq%22%3A%20%22device_log%22%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D' \

The response will be:

{
  "metadata": {
    "page": {
      "totalResults": 1,
      "page": 0,
      "limit": 100
    },
    "sort": [],
    "filter": {
      "name": {
        "in": [],
        "eq": "device_log",
        "notIn": []
      }
    },
    "freeTextSearch": null
  },
  "data": [
    {
      "displayName": "Device Log",
      "name": "device_log",
      "description": null,
      "ownerOrganizationId": null,
      "parentTemplateId": null,
      "id": "c447512b-b72b-4d17-a979-27c9cabe579f",
      "entityTypeName": "generic-entity",
      "removable": true,
      "creationTime": "2022-09-06T09:52:47.496Z",
      "lastModifiedTime": "2022-09-06T09:52:47.496Z"
    }
  ]
}

Save the c447512b-b72b-4d17-a979-27c9cabe579f for later.

Obtaining the organization unique ID

To obtain an organization unique ID, make the following API call:

GET https://your-biot-domain.com/device/v2/devices/001
Replace 001 with your device ID.

The response will be (Abbreviated):

{
  "_id": "001",
  "_ownerOrganization": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Example Inc.",
    "templateId": "2aaa71cf-8a10-4253-9576-6fd160a85b2d"
  },
  "_template": {
    "id": "95fe5241-cb15-4db5-b000-d7d7e02fff0d",
    "name": "DeviceType1",
    "displayName": "DeviceType1"
  },
  ...
}

Save the 00000000-0000-0000-0000-000000000000 for later.

📘

Note

The 00000000-0000-0000-0000-000000000000 id is the defualt organization ID. In your case it might be different.

Uploading a file to BioT

Get a file upload URL:
POST https://your-biot-domain.com/file/v1/files/upload
With body:

{
  "name": "testLogFile.txt",
  "mimeType": "text/plain"
}

The response will be (Abbreviated):

{
  "name": "testLogFile.txt",
  "mimeType": "text/plain",
  "id": "44a154e3-c2b6-469a-a3b1-9fa19cfd388d",
  "signedUrl": "https://dev-file-707227555330.s3.amazonaws.com/44a154e3-c2b6-469a-a3b1-9fa19cfd388d?X-Amz-Security-Token=IQoJb3JpZ2luX2..."
}

Save the file ID 44a154e3-c2b6-469a-a3b1-9fa19cfd388d.

Use the file directly to AWS:
PUT

See this short video for an example.

Attaching a file to a new generic entity instance

To create a new log file generic entity, make the following API call:

POST https://your-biot-domain.com/generic-entity/v1/generic-entities`

{
     "_ownerOrganization": {
          "id": "00000000-0000-0000-0000-000000000000"
     },
     "_name": "logFile1.txt",
     "_templateId": "c447512b-b72b-4d17-a979-27c9cabe579f",
     "txt_log_file": {
          "id": "44a154e3-c2b6-469a-a3b1-9fa19cfd388d"
     },
     "log_file_owner":{
          "id":"001"
     }
}

Downloading the file from the manufacturer portal

You are now ready to download the file from the manufacturer portal.

Login to the portal, and locate the device under the devices tab.
Select the device and click on Expand in the preview pane on the right.
In the window that open locate the tab named Logs and click on it.

If everything went fine, you should see a line that describes the log file you have just uploaded.
Click on it, and then on Expand on the right pane.
You should now be able to see a link to download the file.

Sit back and have a Beer 🍺

Troubleshhoting

1. If any of the API calls fail, make sure that your user has the appropriate permissions to make that API call.
2. If some API calls fail, make sure the attribute names and values are correct. Attributes are case-sensitive and even a small mismatch might cause an error.
3. If you are missing some tabs or fields from the portal UI, make sure that they are not hidden from view.
   Take a look in the Portal Builder configuration under the BioT console for more information.