# Stickers (workflow tags) and notifications [Python]

# Introduction

# About

This tutorial will guide you through the Stickers (workflow tags) and Notifications functionalities.

You are going to use the Stickers (workflow tags) functionality to pass workflow items between two companies. The workflow items will be meter repairs and technical reviews. The two companies will be a company owning water meters and a contractor company taking care of meter repairs and technical reviews.

In addition, you are going to set up notifications so that both companies receive notification messages triggered by the addition of a Sticker (the meter company submitting a request) and the removal of a Sticker (the contractor company confirming that the request is completed).

# Resources

TUTORIAL JUPYTER NOTEBOOK

This tutorial is available as a standalone Jupyter notebook. You can find it in the Trusted Twin public repository in the Trusted Twin Tutorial Resources(opens new window) section.

# Outcomes

  • You are going to set up the environment and create a free Trusted Twin account. Using the User Secret (API key) provided upon creation of the account, you are going to create a role, user and User Secret (API key) that you will use in this tutorial.
  • You are going to create a digital twin consisting of a Twin and a Ledger.
  • You are going to create a user and a role as well as a User Secret (API key) for the contractor company.
  • You are going to use the Stickers functionality from two perspectives - the meter company's perspective and contractor company's perspective.
  • You are going to set up notifications using the Notifications feature so that the contractor company receives a notification when a repair or technical review request is created by the meter company, and the meter company receives a notification once the repair or technical review is completed.

# Preparation

# Requirements

This tutorial requires:

# Install Trusted Twin library

As first step, install the Trusted Twin Python library using the pip package manager for Python.

# Set up your environment

Next, set up your environment.

# Get Super Admin User Secret

On the Trusted Twin platform user authentication is based on User Secrets (API keys).

In order to obtain a Super Admin User Secret (API key):

  1. Go to the Trusted Twin Self-care panel(opens new window) and follow the instructions to create an account.
  2. Once you have created an account, a Super Admin User Secret (API key) for the Super Admin user of the account you created will be displayed.

WARNING

The User Secret (API key) is displayed only once. It is not stored in the Trusted Twin system, and it cannot be retrieved. Keep your User Secret stored in a secure place. If you lose your User Secret, the User Secret generation process will need to be started from the beginning.

# Authenticate requests

Once you have your Super Admin User Secret, you can use it to authenticate requests.

# Get account, user and role

When you create a Super Admin User Secret, a Super Admin user and a Super Admin role are created automatically. You can retrieve the details of your account, your Super Admin user and your Super admin role by calling the "who_am_i" endpoint.

Method Path Operation
GET /whoami who_am_i
GET /roles/{role} get_user-role

Let's retrieve the UUIDs the account, user, and role that the Super Admin User Secret is associated with as well as the details of the Super Admin Role.

The response to the who_am_i endpoint returns information associated with the User Secret (API key) - the account UUID, the user UUID and the role UUID.

The get_user_role response returns the name of the role, information about the user's access to resources and a role statement defining the actions a user can perform on the resources.

WARNING

A Super Admin role allows the user to perform all actions available on the Trusted Twin platform. Also, when new actions related to new features are introduced, they are added by default to the Super Admin role. Therefore, we highly recommend that you create roles for users with permissions that allow them to only perform actions required for their position in the organization and on resources they need to access.

The next step is to create a new role, user and generate a User Secret (API key) for this user. Once they have been generated, you will use this User Secret (API key) moving forward in this tutorial.

# Create meter company role

Let's create a new role to perform operations required for this tutorial.

A role is a collection of permissions:

  • you can "allow" or "deny" "actions" that correspond with endpoint operations (see List of available actions),
  • you can grant permission to resources - specific "twin", "identity" or "ledger" objects.
Method Path Operation
POST /roles create_user_role

You are going to create a role with permissions to perform actions required for this tutorial (see "actions" in the request body below). Please note that the "create", "update", and "delete" actions related to operations on roles, users, and User Secrets should not be included in the list of "actions". It is because the role you are going to create should not be used for user management purposes.

# Create meter company user

After creating a role, create a user with the role.

A user is a person who utilizes the Trusted Twin platform. The permissions of a user to access, create, and manipulate Trusted Twin resources are controlled by the role assigned to the user.

Method Path Operation
POST /users create_user

# Create meter company PIN

A user needs a User Secret (API key) to authenticate on the Trusted Twin platform.

Let's create a User Secret PIN. It will be required to create a User Secret (API key) in the next step. The User Secret PIN can be passed to a third party so that they can create a User Secret for themselves.

Method Path Operation
POST /users/{user}/secrets create_user_secret_pin

WARNING

A User Secret PIN is valid for 10 minutes, and it can be used only once to generate a User Secret (API key). After a User Secret (API key) has been generated, the User Secret PIN automatically expires.

# Create meter company User Secret (API key)

Once you have created a User Secret PIN, you can use it to generate a User Secret (API key).

Method Path Operation
POST /secrets/{account}/{pin} create_user_secret

USER SECRET IS DISPLAYED ONLY ONCE

Please note that the User Secret (API key) is displayed only once. It is not stored in the Trusted Twin system, and it cannot be retrieved. Keep your User Secret stored in a secure place. If you lose your User Secret, you will need to start the User Secret generation process from the beginning.

The result is a User Secret (API key) that we will use throughout this tutorial. We are going to use it to authenticate requests.

# Digital twin

# Create a Twin

You are going to create a digital twin that will represent a water meter. The digital twin will represent a water meter. It will consist of a Twin and a Ledger.

First, let's create a Twin. It is an object on the Trusted Twin platform that ties together all knowledge in the digital twin.

Method Path Operation
POST /twins create_twin

A Twin can have an optional description field. A description of a Twin is always publicly accessible. This means that anyone who knows the unique identifier (UUID) of the Twin will be able to view the description of the Twin.

The Twin you are going to create will have a description field with information about the application name, object type, serial number, and website.

Please note that the description below contains a placeholder (ADD_YOUR_METER_SERIAL_HERE). You need to add a serial number for the meter in place of the placeholder. You can insert any serial number that works for you. In our example, the "serial" is "12345".

As you can see in the response, you are the "owner" and "creator" of the Twin. The owner of a Twin can change the description of the Twin by sending a request to the "update_twin" endpoint if the status of the Twin is "alive".

# Add Ledger Entries

Let's add Entries to the Twin's Ledger.

A Ledger is an object that stores information about the state of a Twin. It contains Entries. They are user-defined key-value pairs.

Method Path Operation
POST /twins/{twin}/ledgers/personal add_twin_ledger_entry

The Entries of your Ledger are going to contain the following information about the state of the Twin:

  • current meter reading ("reading" Entry),
  • battery level ("battery" Entry),
  • log of errors raised through the meter software ("log" Entry),
  • location of where the water meter is installed ("location" Entry).

Please note that in the above "reading" Entry, we used the "visibility" and "history" attributes:

  • The "visibility" attribute defines the visibility of the data in the Entry for other accounts.
  • The "history" attribute defines the time period for which the history of value changes is stored (in our case it is set to 1 month). The History service lets you store historical values of Ledger Entry.

You can execute the above code multiple times to observe the API response for when a given Entry has been already added to the Ledger.

# Digital twin

Let's connect all the above steps into a convenient create_meter() method. It handles all the above operations and creates a digital twin consisting of a Twin and a Ledger.

# Stickers (Preparation)

# About

Stickers (workflow tags) on the Trusted Twin platform are a functionality designed to facilitate workflow processes. They support passing ownership of workflow items (e.g., tasks to be completed) between multiple users. These users can be users belonging the same account where a Sticker was created or to a foreign account. Stickers are attached to Twins.

In this tutorial we are going to demonstrate how the passing of such workflow items works on the example of the meter Twin that you've already created. We are going to assume that you are the owner of the meter and that you hire a third party to:

  • service the meter in case there is a need to repair the meter,
  • perform technical reviews of the meter.

To see how the process works also from the perspective of the contractor company, you are going to create another role, user and User Secret (API key) for the contractor company. The role will have permissions restricted to obtaining details of their own user, role and User Secret (API key) as well as permissions so view Stickers and remove Stickers as well as webhook-related permissions (we are going to use them later on in this tutorial when exploring the Notifications functionality).

# Create contractor role

First, let's create a role for the contractor.

Method Path Operation
POST /twins/{twin}/identities create_twin_identity

# Create contractor user

After creating a role, let's create a user with the above role.

Method Path Operation
POST /users create_user

# Create contractor PIN

The contractor needs a User Secret (API key) to authenticate on the Trusted Twin platform.

Let's create a User Secret PIN for the contractor. The PIN will be required to create a User Secret (API key) in the next step.

Method Path Operation
POST /users/{user}/secrets create_user_secret_pin

WARNING

A User Secret PIN is valid for 10 minutes, and it can be used only once to generate a User Secret (API key). After a User Secret (API key) has been generated, the User Secret PIN automatically expires.

# Create contractor User Secret

Now, create a User Secret (API key) for the contractor.

Method Path Operation
POST /secrets/{account}/{pin} create_user_secret

WARNING

Please note that the User Secret is displayed only once. It is not stored in the Trusted Twin system, and it cannot be retrieved. Keep your User Secret stored in a secure place. If you lose your User Secret, you will need to start the User Secret generation process from the beginning.

The result is a User Secret (API key) that we will use throughout this tutorial. We are going to use it to authenticate requests send by the contractor.

# Stickers

# Get Twin Stickers (meter company)

Stickers (workflow tags) are attached to a Twin. First, we are going to check whether any Stickers are attached to the meter Twin. Please note that you can only see stickers where you are a recipient of the sticker (i.e., your UUID is included in the "recipients" list).

Method Path Operation
GET /twins/{twin}/stickers/ get_stickers

There should be no Stickers attached to the Twin yet.

# Put Stickers on Twin (meter company)

Let's create two Stickers to represent repair requests and assign them to the following users:

  • _CONTRACTOR_USER: the user who should perform the repairs and technical reviews,
  • _COMPANY_USER: the meter company user who is creating the Sticker. This will allow the meter company user to view this Sticker.

The validity of the Stickers will be set to one day from the moment the Stickers are created. Please note that we are adding as well the "publish" attribute. It will allow us to set notifications for the Stickers in the next chapter.

Method Path Operation
POST /twins/{twin}/stickers/ put_sticker

# Get Twin Stickers (meter company)

Let's check again if there are any Stickers attached to the Twin.

Method Path Operation
GET /twins/{twin}/stickers/ get_stickers

We can see that the Stickers we just created are attached to the Twin.

# List Stickers (contractor)

Let's change the perspective and get into the shoes of the contractor company. Check if you have any Stickers (requests) assigned.

Method Path Operation
GET /stickers get_stickers

The response should return two Stickers (requests) as there are two Stickers assigned to the contractor user.

# Remove Sticker (contractor)

After completing the repair, remove a Sticker from the Twin.

Please note that the operation of removing Stickers is atomic i.e., after one user has removed a Sticker from the Twin this Sticker is no longer attached to the Twin.

Method Path Operation
DELETE /twins/{twin}/stickers/{color} remove_sticker

Let's remove the "red" Sticker from the Twin.

# List Stickers (contractor)

Confirm (still as the contractor company) that the Sticker is no longer on your task list.

Method Path Operation
GET /stickers get_stickers

Let's retrieve all Stickers assigned to you.

# Get Sticker (meter company)

Let's change the perspective back to the perspective of the meter owner. Check whether the "red" Sticker is still attached to the Twin.

Method Path Operation
GET /twins/{twin}/stickers/{color} get_sticker

We should receive an error message stating that the Sticker of the given color was not found if you search for the _COLOR "red".

# Notifications

# About

Let's automate our workflow process further. Our goal is that:

  • the service company receives a notification when a service request is created,
  • we receive a notification once the meter is serviced,
  • we receive a notification once a service request expires.

# Subscribe to a webhook (contractor)

First, create a subscription as the contractor company to receive a notification every time a Sticker (request) is created and assigned to you.

Method Path Operation
POST /notifications/webhooks webhook_subscribe

Please note that you will have to provide a callback url to which the subscription confirmation and notification messages will be sent. You can use a temporary URL by creating a public bin on the requestbin.com(opens new window) website.

The value of the "topic" parameter must be equal to the "color" (name) of the Sticker.

# Confirmation message received (contractor)

After creating the subscription, you should receive a confirmation message similar to the message below to the callback URL.

# Confirm webhook subscription (contractor)

As next step, you need to confirm the webhook subscription.

Method Path Operation
GET /notifications/webhooks/?token={token} webhook_confirm_subscription

Use the token from the "confirmation_url" (you will find it in the confirmation message) to confirm the webhook subscription.

# Put Sticker on a Twin (meter company)

Now that we have subscribed to a webhook and confirmed the subscription, each time there is a new sticker (request) created for the contractor company, they will receive a notification message.

Method Path Operation
POST /twins/{twin}/stickers put_sticker

Let's trigger a notification event by adding a Sticker of the given color to the Twin.

# Notification message received (contractor)

You should have received a notification message for the contractor company to the callback URL you provided earlier. The notification message should look similar to the message below:

# Subscribe to a webhook (meter company)

Let's change the perspective and create a subscription as if we were the company owning the meters. We want to get notified of any Stickers that will get removed from the Twin. We will create a subscription with the topic "task-completed".

Method Path Operation
POST /notifications/webhooks webhook_subscribe

# Confirmation message received (meter company)

After creating a subscription, you will receive a subscription confirmation to the "callback_url". The confirmation will look similar to the message below.

# Confirm webhook subscription (meter company)

Method Path Operation
GET /notifications/webhooks/?token={token} webhook_confirm_subscription

# Remove Sticker (contractor)

Let's remove the Sticker to see if it triggers a notification message.

Method Path Operation
DELETE /twins/{twin}/stickers/{color} remove_sticker

# Notification message received (meter company)

Was this article helpful?