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
Filename - the file name of the binary file
Binary - The file in binary data format
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