Created on 27 April 2021
icon_unfollowing
Login to follow
annotation-services

Annotation Services

Stable version 1.0.1 (Compatible with OutSystems 11)
Uploaded on 27 April 2021 by 
annotation-services

Annotation Services

Documentation
1.0.1

Terms used in Annotation Services

Annotation

An annotation is typically additional information to an already existing information. 

Body

The body of an annotation is either plain text or a binary file. A binary file can be e.g. a voice recording or a drawing which further clarifies a text document.

Target

An annotation always extends other information - the target. The target can be everything ranging from a digital document to a physical item. A target is identified by a type (e.g. "document") and a unique identifier. An annotation can target multiple items.

Metadata

The target type and identifier might not be enough to know where this annotation concretely belongs to. Additional Metadata helps. That can be a page number, or a certain point in time this annotation belongs to.

How to start

1. Create a new application

2. Add dependency to AnnotationServices_API and Annotation_Core_CS

3. Create a new Server Action "Setup"

4. From AnnotationServices_API add the Action Definition_Setup to your action flow.

A definition is a bracket around the annotations, target types and metadata you want to save (and search) in your application. The Setup Action takes the following structure as input

DefinitionId - A unique identifier for this definition. (Guid recommended)

Name and Description - Your choice

TargetTypes - List Structure of target types and optional metadata

Id - A unique identifier for this definition (Guid recommended)

Name and Alias - Your choice

Schema (optional) - Metadata Definition.

Key - Name of the property (recommended lowercase and no white space)

IsRequired - If True this Property must be set when adding this target type

Definition_Setup does only create a definition one time. If a definition with that id already exists it skips the creating. It does not update anything. The same is true for target types. Already existing target types are skipped and not modified. However you can add addtional target types.

5. Add a timer for the Setup Action and set to When published.


How to add annotations

You can add plain text or binary file annotations to your repository with the following server actions

Annotation_AddTextAnnotation - for adding a plain text annotation

Annotation_AddBinaryAnnotation - for adding a binary file annotation

Parameters for Text Annotation

ParentId - If you want to establish an annotation hierarchy you can set this to the parent's annotation id

AnnotationDefinitionId - the definition id this annotation belongs to

Text - the actual plain text of the annotation

Targets (List) - one or more targets this annotation belongs to

TargetTypeId - The type id

Source - A unique identifier describing the target. Can be anything. For example, a URL or a document id from your document management system

Metadata (List of Key Value Pairs) - If you defined a Schema for the target type the data for your schema.

CreatedOn - When this annotation was created

CreatedBy - The user id who created the annotation

Parameters for Binary Annotation

ParentId - If you want to establish an annotation hierarchy you can set this to the parent's annotation id

AnnotationDefinitionId - the definition id this annotation belongs to

Filename - the file name of the binary file

Binary - The file in binary data format

Targets (List) - one or more targets this annotation belongs to

TargetTypeId - The type id

Source - A unique identifier describing the target. Can be anything. For example, a URL or a document id from your document management system

Metadata (List of Key Value Pairs) - If you defined a Schema for the target type the data for your schema.

CreatedOn - When this annotation was created

CreatedBy - The user id who created the annotation

Both actions return an AnnotationId.


How to retrieve annotations

To retrieve annotations, use the service action Annotation_GetAnnotations

Filter parameters

SearchFieldList - List of search criteria (AND)

AnnotationFieldSearchTypeId - Select the field to use a criterion. If you want to use one of your metadata fields as criteria leave blank.

FieldName - Only valid if AnnotationFieldSearchTypeId is empty. Must be a key from your target schema

FieldValue - The value you want to compare.


For every SearchField a = filter is set. Except for Text which uses a LIKE filter.

PageIndex - Current Page of search results to return

MaxRecords - the maximum records to return per page




Support options
This asset is not supported by OutSystems. You may use the discussion forums to leave suggestions or obtain best-effort support from the community, including from  who created this asset.
Dependencies
Annotation Services has no dependencies.