Tutorial: How to Create Annotation Tags

Using the Experimenter's Portal

Experimenters can create and manage the Tag Domains and Tags of their experiment using the Experimenter's portal Annotation interface.

Annotations EP

In more detail, each experiment created using the Experimenter's Portal automatically owns and is associated with a single TagDomain named after the Experiment.

Annotations EP

Using this interface, experimenters can select and add more TagDomains to their experiment if needed, by clicking on the list of "Predefined tag domains" available.

Annotations EP

Also it is possible for experimenters to create new TagDomains and add/remove Tags to them using the following interface.

Annotations EP

Using the API

Alternatively, users can interact with the Annotation Service using the provided Restful API. The full description of the API is available here.

Creation of a TagDomain

To create a TagDomain experimenters need to use the domainCreate API call.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
  "description": "a tag domain for faulty noise level",
  "tags": [
    {
      "id": 123,
      "name": "faulty",
      "urn": "urn:tag:faulty"
    },
    {
          "id": 132,
          "name": "normal",
          "urn": "urn:tag:normal"
    }
  ],
  "urn": "urn:tagDomain:86d7edce-5092-44c0-bed8-da4beaa3fbc6:malfunctioning"
}' 'https://annotations.organicity.eu/admin/tagDomains'

Retrieval of a TagDomain

To retrieve the information of a TagDomain experimenters need to use the domainFindByUrn API call.

curl -X GET --header 'Accept: application/json' 'https://annotations.organicity.eu/tagDomains/urn%3AtagDomain%3A86d7edce-5092-44c0-bed8-da4beaa3fbc6%3Amalfunctioning'

Listing of Tags of TagDomain

To retrieve the tags of a TagDomain experimenters need to use the domainGetTags API call.

curl -X GET --header 'Accept: application/json' 'https://annotations.organicity.eu/tagDomains/urn%3AtagDomain%3A86d7edce-5092-44c0-bed8-da4beaa3fbc6%3Amalfunctioning/tags'

Associate Experiment with an Tag Domain

To add a TagDomain to the list of selected TagDomains of an Experiment experimenters need to use the experimentAddTagDomains API call.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' 'https://annotations.organicity.eu/admin/applications/urn%3Aapplication%3A86d7edce-5092-44c0-bed8-da4beaa3fbc6/tagDomains?tagDomainUrn=urn%3AtagDomain%3A86d7edce-5092-44c0-bed8-da4beaa3fbc6%3Amalfunctioning'

Using the Java Client

Also, users can interact with the Annotation Service using the available JAVA and Android client for the Annotation Service. The code of the Annotation Service Clients is available here.

Using in Maven

To use the Annotation Service Client in Java project you need to add the following dependency in you pom.xml.

<repositories>
    <repository>
        <id>organicity</id>
        <url>https://maven.organicity.eu/content/repositories/snapshots</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>eu.organicity</groupId>
        <artifactId>annotations-client</artifactId>
        <version>1.0-SNAPSHOT</version>
    </dependency> 
</dependencies> 

Using in Gradle for Android

To use the Annotation Service Android Client in Android application you need to add the following dependency in you build.gradle.

repositories {
    mavenLocal()
    mavenCentral()
    maven { url 'https://maven.organicity.eu/content/repositories/snapshots' }
}

dependencies {
    compile('eu.organicity:annotations-android-client:1.0-SNAPSHOT') {
        exclude module: 'spring-boot-starter'
        exclude module: 'spring-web'
        exclude module: 'jackson-annotations'
        exclude module: 'jackson-databind'
        exclude module: 'spring-boot-starter-logging'
        exclude module: 'jackson-mapper-asl'
        exclude module: 'commons-logging'
    }
}

Creation of a TagDomain

final AnnotationServiceClient client =  new AnnotationServiceClient("client_id", "client_secret", "username", "password");
final String TAG_DOMAIN = "urn:oc:tagDomain:EmptyStation";
client.addTagDomain(TAG_DOMAIN, "Describes Emptiness");
client.addTag(TAG_DOMAIN, "urn:oc:tagDomain:EmptyStation:empty", "Empty");
client.addTag(TAG_DOMAIN, "urn:oc:tagDomain:EmptyStation:nonempty", "Non Empty");

Retrieval of a TagDomain

final AnnotationServiceClient client =  new AnnotationServiceClient("client_id", "client_secret", "username", "password");
TagDomainDTO dto = client.getTagDomain("urn:oc:tagDomain:AnomalyDetection");
System.out.println(dto);

Listing of Tags of TagDomain

final AnnotationServiceClient client =  new AnnotationServiceClient("client_id", "client_secret", "username", "password");
TagDTO[] tags = client.getTags("urn:oc:tagDomain:AnomalyDetection");
for (TagDTO tag : tags) {
    System.out.println(tag);
}

Associate Experiment with an Tag Domain

final AnnotationServiceClient client =  new AnnotationServiceClient("client_id", "client_secret", "username", "password");
ExperimentDTO dto = client.experimentAddTagDomains("expeirment", "urn:oc:tagDomain:AnomalyDetection");
System.out.println(dto);

Post an Annotation

final AnnotationServiceClient client =  new AnnotationServiceClient("client_id", "client_secret", "username", "password");
AnnotationDTO dto = new AnnotationDTO();
dto.setApplication("nameOftheApplication");
dto.setAssetUrn("urn:oc:entity:patras:easybike:bikestation:293:301");
dto.setUser("organcity sub of the user if available");
dto.setNumericValue(0.0);
dto.setTagUrn("urn:oc:tagDomain:IndoorHumidityLevels:high");
dto.setTextValue("");
dto = client.postAnnotation(dto);
System.out.println(dto);

Listing All Annotations

final AnnotationServiceClient client =  new AnnotationServiceClient("client_id", "client_secret", "username", "password");
AnnotationDTO[] annotations = client.getAnnotations();
for (AnnotationDTO annotation : annotations) {
    System.out.println(annotation);
}

Posting Annotations

Now lets jump to posting annotations.