annotation-add

Enqueues contents as standard annotations, attributed to the specified user, on a specific document in a collection. The name of the annotation is specified in the <content> node's name attribute. Each user can associate multiple instances of any standard annotation with each document. The SOAP name of this function is: AnnotationAdd

Synopsis

void annotation-add(collection, subcollection, content, document-vse-key, document-vse-key-normalized, username, acl, synchronization, priority, datesecs, weight);
nmtoken collection;
enum subcollection;
content nodeset content;
string document-vse-key;
boolean document-vse-key-normalized;
string username;
string acl;
enum synchronization;
int priority;
int datesecs;
int weight;

Parameters

  • nmtoken collection - The name of the collection that holds the document to which you want to add an annotation. (Required)
  • enum subcollection - The subcollection in which to enqueue. Default value: live. Possible values: live|staging.
  • content nodeset content - A <content> node to be added to a document. Minimally needs a name attribute and a value. (Required)
  • string document-vse-key - The vse-key of the document to which this content should be added. (Required)
  • boolean document-vse-key-normalized - If set to "true", the document-vse-key will be treated as if it has already been normalized and will not go through any additional normalization. If set to "false", the document-vse-key will be normalized. Default value: true.
  • string username - The user name to which this annotation should be attributed. (Required)
  • string acl - The ACL to use. (Required)
  • enum synchronization - The synchronization mode to use. Default value: indexed. Possible values: enqueued|indexed|none|to-be-crawled|to-be-indexed|indexed-no-sync|none.
  • int priority - The priority that this content enqueue should be in relation to anything else being crawled at the same time. Default value: 1.
  • int datesecs - The date and time, in seconds since the epoch, that the annotation will be marked as having occurred. If not set, the current time will be used. Useful for restoring annotations from a backup file.
  • int weight - Weight attribute to add to the content. Affects ranking - matches in a content with higher weight are more important. Default value: 1.

Exceptions

  • annotation-content-missing-name-attribute
  • annotation-content-missing-value
  • search-collection-invalid-name
  • search-collection-enqueue

Authentication

Like all Watson Explorer Engine API functions except for ping, the annotation-add function requires authentication.

When using REST, you can simply pass v.username and v.password as CGI parameters via HTTP or HTTPS to authenticate the REST call to the annotation-add function.

When using the SOAP API, you can pass credentials as parameters on an endpoint, or you can leverage the authentication method that is supported by all Watson Explorer Engine functions. Each provides a setAuthentication method that can be passed an authentication object to provide the user name and password under which a function runs. An example of this in Java for a SOAP call to the annotation-add function is the following:

    Authentication authentication = new Authentication();
    authentication.setUsername("joe-user");
    authentication.setPassword("joes-password");

    AnnotationAdd foo = new AnnotationAdd();
    foo.setAuthentication(authentication);

A single authentication object would typically be reused throughout each individual application.