NFC Tags

NFC Tags can be used with the devices to trigger a workflow. In this section, we will discuss how to register an NFC tag and use it in a workflow.

🚧

In Beta

As you read through this section, you may notice that the steps required to configure NFC tags for workflow triggers is a bit rough. Our tooling to address this and make it easier/consistent is not yet complete. Instead of not letting you try the NFC tags until better tools are available, we instead give you the option to use the raw curl commands as described below, so you can try out NFC tags now. Better tools are coming, we ask for your patience until they arrive. Thanks!

NFC Tags

To use an NFC tap to trigger workflows on a Relay, a user taps a Relay on an NFC tag and it triggers the workflow registered to that tag. It is a simple and secure way to verify that the user is within reach of the NFC sticker.

Setup

The first step would be to register the NFC tag's unique id to the Relay server. You will need the unique URN that is stored within your NFC tag. Use an NFC tools app (Android | iOS) on your phone, or any NFC reader to read that tag and retrieve the tag_uri value which should look similar to this:

https://www.relaypro.com/nfc?picc_data=AFF04066E01F91F4C261151234567890&cmac=D06213EE41234567

Although this looks like a web site URL, it isn't, so don't bother pasting it into a web browser. It is a unique identifier that provides a namespace for this data, along with signed data from the tag.

Along with the tag_uri value, you will also need an access token and your subscriber ID. You can find your subscriber ID through the CLI using the relay subscriber list command, which lists all of the subscriber IDs associated with your account. To get the access token, you will first need to get your refresh token. You can follow the steps on the Auth for HTTP APIs section to get your access token.

Next we will POST the tag_uri to the Relay server to register it. Here is what the payload for the POST request should look like:

{
  "tag_uri": "https://www.relaypro.com/nfc?picc_data=B3BFC22FBF30231947D156F69BEDD6B9&cmac=BACFEED47DBF9660",
  "content": {
    "type": "custom",
    "category": "my_category",
    "label": "Location 1"
  }
}

Note that the "type" should always be "custom", that is the special value which enables this NFC tag to be used to trigger workflows. Beyond that, you can add any key/value pairs you want for either mapping this to trigger workflow(s), and/or to pass data in to your workflows, or to help you distinguish between different NFC tags. In the example above, we've added the keys "category" and "label".

Now we can register this tag with the Relay server. Here is what the curl command with the payload and authorization should look like:

$ ACCESS_TOKEN="2b937946e9b38184f7080ddfd06c9488"
$ TAG_URI="https://www.relaypro.com/nfc?picc_data=B3BFC22FBF30231947D156F69BEDD6B9&cmac=BACFEED47DBF9660"
$ SUBSCRIBER_ID="ee4547e0-aaef-4956-b853-ade123456789"
$ curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "User-Agent: my_client" \
    -X POST \
    -d "{ 'tag_uri': '$TAG_URI', \
          'content': { 'type': 'custom', 'category': 'my_category', 'label': 'Location 1' } }" \
     "https://all-main-pro-ibot.relaysvr.com/ibot/relay_nfc_tag?subscriber_id=$SUBSCRIBER_ID"

The successful response to that curl command should be a 201 (created), along with a response document that looks like this:

{"content":{"label":"Location 1","category":"my_category","type":"custom"},"counter":16,"subscriber_id":"ee4547e0-aaef-4956-b853-ade123456789","tag_id":"5D6bLBhrw4KgiQqyZABCDE","uid":"04b432ca967890"}

If you want to update any of the registration info above for this tag later, you can repeat the process including the POST, and you should get a 201 response with the updated response document.

Register a workflow

The next step after registering the tag uri with the Relay server, is to register the workflow and device to that uri. You can use the additional key/value pairs you added above for matching to your workflow. In the example below, we'll match on category. The "type":"custom" pair is always required. Here is what the payload for that should look like:

{
    "name": "my NFC workflow",
    "install": ["990008473937489"],
    "config_content_type": "application/json",
    "config": {
        "trigger": {
            "on_nfc": {
                "type": "custom",
                "category": "my_category"
            },
            "start": {
                "workflow": {
                    "uri": "wss://your_workflow_uri.com/workflow"
                }
            }
        }
    }
}

Now that you know what the payload is, you can make that POST request to register a workflow for an NFC tap:

$ ACCESS_TOKEN="3c388bb1e69244ec2fc5e2209df3d1cc"
$ SUBSCRIBER_ID="ee4547e0-aaef-4956-b853-ade123456789"
$ curl -vv -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -H "User-Agent: my_client" \
    -d '{ "name": "my NFC workflow",
          "install": ["990008473937489"],
          "config_content_type": "application/json",
          "config": {
              "trigger": {
                  "on_nfc": {
                      "type": "custom",
                      "category": "my_category"
                   },
                  "start": {
                      "workflow": {
                          "uri": "wss://your_workflow_uri.com/workflow"
                       }
                   }
              }
          }
      }' "https://all-main-pro-ibot.relaysvr.com/ibot/workflow?subscriber_id=$SUBSCRIBER_ID"

This should return a 201 code, with a response document like the following:

[{"config":{"trigger":{"on_nfc":{"type":"custom","category":"my_category"},"start":{"workflow":{"uri":"wss://your_workflow_uri.com/workflow"}}}},"config_content_type":"application/json","install":["990007560000945"],"name":"my NFC workflow","options":{"profiling":false,"singleton":true},"subscriber_id":"ee4547e0-aaef-4956-b853-ade123456789","workflow_id":"wf_myNFCworkflow_V23CJGLhv8u2wdammDFXAD"}]

And now you should be good to go. Now when you tap your Relay against that NFC tag, it should successfully trigger the registered workflow!

Usage

When a workflow does get triggered by an NFC tap, this is what the trigger looks like in the START event:

{'args': {'nfc_payload': {'label': 'Location 1', 'category': 'my_category'}, 'source_uri': 'urn:relay-resource:name:device:Remarkable%20Relay', 'uid': '04b432ca967890'}, 'type': 'nfc'}

And how you can reference it in your workflow:

workflow.on(Event.START, async (event) => {
    const { trigger: { args: { nfc_payload, source_uri } } } = event
    if (nfc_payload) {
        log(nfc_payload)
        await workflow.setVar('my_var', nfc_payload.label)
...