Tags #### Devicehub can generate tags, which are synthetic identifiers that identify a device in an organization. A tag has minimally two fields: the ID and the Registration Number of the organization that generated such ID. In Devicehub tags are created empty, this is without any device associated, and they are associated or **linked** when they are assigned to a device. In Devicehub you usually use the AndroidApp to link tags and devices. The organization that created the tag in the Devicehub (which can be impersonating the organization that generated the ID) is called the **tag provider**. This is usual when dealing with other organizations devices. A device can have many tags but a tag can only be linked to one device. As for the actual implementation, you cannot unlink them. Devicehub users can design, generate and print tags, manually setting an ID and a tag provider. Note though that these virtual tags don't have to forcefully be printed or have a physical representation (this is not imposed at system level). Tags are case insensitive and are converted to lower-case in Devicehub. eTags ***** We recognize a special type of tag, the **eReuse.org tags (eTag)**. These are tags defined by eReuse.org and that can be issued only by tag providers that comply with the eReuse.org requisites. The eTags are designed to empower device exchange between organizations and identification efficiency. They are built with durable plastic and have a QR code, a NFC chip and a written ID. These tags live in separate databases from Devicehubs, empowered by the `eReuse.org Tag `_ software. By using this software, eReuse.org certified tag providers can create and manage the tags, and send them to Devicehubs of their choice. The section *Use-case with eTags* shows the use-case of these eTags. Tag ID design ============= The eTag has a fixed schema for its ID: ``XXX-YYYYYYYYYYYYYY``, where: - *XX* is the **eReuse.org Tag Provider ID (eTagPId)**. - *YYYYYYYYYYYY* is the ID of the tag in the provider.. The eTagPid identifies an official eReuse.org Tag provider; this ID is managed by eReuse.org in a public repository. eTagPIds are made of 2 capital letters and numbers. The ID of the tag in the provider (*YYYYYYYYYYYYYY*) consists from 5 to 10 capital letters and numbers (registering a maximum of 10^12 tags). As an example, ``FO-A4CZ2`` is a tag from the ``FO`` tag provider and ID ``A4CZ2``. Creating tags ************* You need to create a tag before linking it to a device. There are two ways of creating a tag: - By performing ``POST /tags?ids=...`` and passing a list of tag IDs to create. All users can create tags this method, however they cannot create eTags. Get more info at the endpoint docs. - By executing in a terminal ``flask create-tags `` and passing a list of IDs to create. Only an admin is supposed to use this method, which allows them to create eTags. Get more info with ``flask create-tags --help``. Note that tags cannot have a slash ``/``. Linking a tag ************* Linking a tag is joining the tag with the device. In Devicehub this process is done when performing a Snapshot (POST Snapshot), by setting tag ids in ``snapshot['device']['tags']``. Future implementation will allow setting to the organization to ensure tags are inequivocally correct. Note that tags must exist in the database prior this. You can only link once, and consecutive Snapshots that have the same tag will validate that the link is correct –so it is good praxis to try to always provide the tag when performing a Snapshot. Tags help too in finding devices when these don't generate a ``HID``. Find more in the ``Snapshot`` docs. Getting a device through its tag ******************************** When performing ``GET /tags//device`` you will get directly the device of such tag, as long as there are not two tags with the same tag-id. In such case you should use ``GET /tags///device`` to unequivocally get the correct device (feature to develop). Tags and migrations ******************* Tags travel with the devices they are linked when migrating them. Future implementations can parameterize this. Use-case with eTags ******************* We explain the use-case of tagging a device with an :ref:`tags:eTags`, going through the manufacturing of the tags, their distribution and the final linkage between tag and computer. For this use-case we suppose we want 100 eTags. Actors ====== - Tag provider: organization that orders and manages the eTags; it is certified by eReuse.org thus having permission to order the tags. - NFC Tag manufacturer. - Photochromic tag manufacturer. - User: organization that uses the tags. Requirements ============ - At least one eReuse.org Devicehub. One Devicehub can contain several organizations and inventories, or organizations can have their own copy of Devicehub. Devicehub work distributely over the Internet. - One `eReuse.org Tag `_ running in a server over the Internet by the *tag provider*. Use case ======== 1. The *tag provider* enters into the server containing the *eReuse.org Tag* software and executes the command ``etag create-tags 100 --csv file.csv``, which creates 100 tags in the database and saves their URLs into a spreadsheet CSV file called *file.csv*. 2. The *tag provider* sends the CSV file to the *NFC tag manufacturer* and orders the 100 tags. 3. The *NFC tag manufacturer* creates those tags (NFC plus QR code) and updates the CSV file with the NFC ID of each tag, so each row of the CSV file contains the URL sent by the *tag provider* and the ID of the NFC tag created by the *NFC tag manufacturer*. 4. The *Tag provider* updates *eReuse.org Tag* with the ID of the NFC by executing ``etag update-tags file.csv`` where *file.csv* is the file sent by the *NFC tag manufacturer*. 5. The *Tag provider* orders 100 photochromic tags to the *Photochromic tag manufacturer*. Note that these tags don't require any special treatment. 6. The *Photochromic tag manufacturer* sends back 100 tags. 7. The *Tag provider* distributes the eTags (NFC and photochromic) to several organizations, *users*, both physically by sending them and virtually by executing ``etag set-tags http://some-devicehub.com 0 100``; this marks the tags in *eReuse.org Tag* as *sent to some-devicehub.com* and creates the tags in that Devicehub. 8. The *user* receives the tags, sticks them in their devices, and scans the NFC or QR codes: 1. By using the `eReuse.org Android App `_ the user can scan the QR code or the NFC of the eTag. 2. If the *user* is processing devices with the `eReuse.org Workbench `_, Workbench automatically attaches hardware information like serial numbers, otherwise the *user* can add that information through the app. 3. These softwares communicate with the Devicehub of the user and command the Devicehub to link the device with the tag. 4. The Devicehub of the user links the tag. 5. The Devicehub creates or updates a virtual entity in Everythng containing the device and the tag. 6. If Devicehub or Everythng detect that the tag was linked they won't allow this operation. Devicehub can only detect if the app is linked by looking at its internal database. Everythng, as it contains all device and tag information, validates that the tag is not linked elsewhere.