FileHold viewers - Custom preset annotations

The FileHold viewer level 2 and 3 supports several different types of annotations. Annotations allow users to add stamps, text, sticky notes, shapes, highlights and so on to documents in the FileHold library. The properties of an annotation (style, colour, font, etc.) do not persist from document to document but some preset stamps are available: Paid, Approved, Rejected, Expunged. The existing annotation presets can be modified or new preset annotations can be created in the Microsoft SQL database for reuse. If you have common annotations that you would like to use, you can create and customize preset annotations using this guide.

Only database administrators who have access and are skilled with Microsoft SQL server should attempt modifying or creating new annotation presets. Annotation preset modifications are not included in your FileCare agreement. FileHold professional services are available if assistance is needed.

Annotation properties

The following properties are available for each annotation type and their default values. In other words, how the annotation looks "out of the box".

IDNameTypeDefault value
borderWidthBorder widthFloat0.2
dashCapDash capInt0
dashStyleDash styleInt0
fillFillBooleanFalse
fillColorFill colorString#000000
strokeStrokeBooleanTrue
strokeColorStroke colorString#FF0000
fontNameFont nameStringArial
fontStyleFont styleInt1
foreColorText colorString#FF0000
textTextStringSTAMP
radiusFactorRadius factorFloat0.25
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.04
dashCapDash capInt0
dashStyleDash styleInt0
fillFillBooleanFalse
fillColorFill colorString#FFFFFF
strokeStrokeBooleanTrue
strokeColorStroke colorString#000000
squaredBoxSquared boxBooleanFalse
radiusFactorRadius factorFloat0
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
fillColorFill colorString#FFFF00
squaredBoxSquared boxBooleanFalse
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.04
dashCapDash capInt0
dashStyleDash styleInt0
startCapStart capInt0
endCapEnd capInt0
strokeColorStroke colorString#000000
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
arrowFilledArrow filledBooleanTrue
arrowHeightArrow heightInt10
arrowWidthArrow widthInt5
borderWidthBorder widthFloat0.04
dashCapDash capInt0
dashStyleDash styleInt0
strokeColorStroke colorString#000000
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.04
dashCapDash capInt0
dashStyleDash styleInt0
fillFillBooleanFalse
fillColorFill colorString#000000
strokeStrokeBooleanTrue
strokeColorStroke colorString#000000
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.04
dashCapDash capInt0
dashStyleDash styleInt0
fillFillBooleanFalse
fillColorFill colorString#FFFFFF
strokeStrokeBooleanTrue
strokeColorStroke colorString#000000
squaredBoxSquared boxBooleanFalse
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.01
dashCapDash capInt0
dashStyleDash styleInt0
fillFillBooleanTrue
fillColorFill colorString#FFFFFF
strokeStrokeBooleanFalse
strokeColorStroke colorString#000000
fontNameFont nameStringArial
fontSizeFont sizeInt12
fontStyleFont styleInt0
foreColorText colorString#000000
alignmentHorizontal alignmentInt0
lineAlignmentVertical alignmentInt0
textTextStringText
autoSizeAuto sizeBooleanFalse
radiusFactorRadius factorFloat0
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.01
dashCapDash capInt0
dashStyleDash styleInt0
fillFillBooleanTrue
fillColorFill colorString#FDFD32
strokeStrokeBooleanTrue
strokeColorStroke colorString#000000
fontNameFont nameStringArial
fontSizeFont sizeInt20
fontStyleFont styleInt1
foreColorText colorString#000000
alignmentHorizontal alignmentInt0
lineAlignmentVertical alignmentInt0
textTextStringText
autoSizeAuto sizeBooleanFalse
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.04
dashCapDash capInt0
dashStyleDash styleInt0
strokeColorStroke colorString#000000
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.2
strokeColorStroke colorString#FFFF00
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.04
dashCapDash capInt0
dashStyleDash styleInt0
strokeColorStroke colorString#000000
fontNameFont nameStringArial
fontSizeFont sizeInt12
fontStyleFont styleInt0
foreColorText colorString#000000
measurementUnitMeasurement unitInt1
scaleScaleFloat1
opacityOpacityFloat1
rotationRotationInt0
IDNameTypeDefault value
borderWidthBorder widthFloat0.04
dashCapDash capInt0
dashStyleDash styleInt0
fillFillBooleanFalse
fillColorFill colorString#000000
strokeStrokeBooleanTrue
strokeColorStroke colorString#000000
fontNameFont nameStringArial
fontSizeFont sizeInt12
fontStyleFont styleInt0
foreColorText colorString#000000
measurementUnitMeasurement unitInt1
scaleScaleFloat1
opacityOpacityFloat1
rotationRotationInt0

 

Annotation property descriptions

The table below describes the available options for the annotation properties.

IDNameTypeDescription
borderWidthBorder widthFloat

In viewer dialogs, this value is multiplied by 96, i.e. 0.2 is presented as 19.2.

Predefined values:

  • Extra thin – 0.01
  • Thin – 0.02
  • Normal – 0.04
  • Strong – 0.08
  • Very strong – 0.1
dashCapDash capInt

Applicable only when dash style is other than solid.

Allowed values:

  • 0 – flat
  • 2 – round
  • 3 – triangle

More details here

dashStyleDash styleInt

Allowed values:

  • 0 – solid
  • 1 – dash
  • 2 – dot
  • 3 – dash dot
  • 4 – dash dot dot

More details here

startCapStart capInt

Cap style used at the start of drawn line.

Allowed values:

  • 0 – flat
  • 1 – square
  • 2 – round
  • 3 – triangle
  • 16 – no anchor
  • 17 – square anchor
  • 18 – round anchor
  • 19 – diamond anchor
  • 20 – arrow anchor
  • 240 – anchor mask

More details here

endCapEnd capIntCap style used at the end of drawn line. Allowed values are the same like for startCap property.
fillColorFill colorStringHexadecimal color code, i.e. #FFFFFF
strokeStrokeBoolean

Determines whether a stoke should be visible or not.

Allowed values:

  • True
  • False
strokeColorStroke colorStringHexadecimal color code, i.e. #FFFFFF
fontNameFont nameStringName of font to be used to render the text
fontSizeFont sizeIntFont size in pixels
fontStyleFont styleInt

Allowed values:

  • 0 – regular
  • 1 – bold
  • 2 – italic
  • 4 – underline
  • 8 – strikeout
foreColorText colorStringHexadecimal color code, i.e. #FFFFFF
alignmentHorizontal alignmentInt

Allowed values:

  • 0 – left
  • 1 – center
  • 2 – right
lineAlignmentVertical alignmentInt

Allowed values:

  • 0 – top
  • 1 – middle
  • 2 – bottom
textTextStringText value to be displayed as annotation content.
autoSizeAuto sizeBoolean

Determines whether annotation should be automatically resized to its contents or not.

Allowed values:

  • True
  • False
squaredBoxSquared boxBoolean

Determines whether annotation should have the same width and height.

Allowed values:

  • True
  • False
radiusFactorRadius factorFloat

Determines (in %) how rounded should be drawn borders. 0 means 0% rounded borders, 1 means 100% rounded borders.

Allowed float numbers in the range from 0 to 1.

measurementUnitMeasurement unitInt

Determines a unit to be presented next to the calculated distance.

Allowed values:

  • 0 – pixel
  • 1 – inch
  • 2 – centimeter
  • 3 – millimeter
scaleScaleFloat

Determines a scale of the ruler. Presented distance will be calculated with this formula:

distance = inches * scale

arrowFilledArrow filledBoolean

Determines whether arrow should be filled or not.

Allowed values:

  • True
  • False
arrowHeightArrow heightIntDetermines height of the arrow in inches.
arrowWidthArrow widthIntDetermines width of the arrow in inches.
opacityOpacityFloat

Determines (in %) an opacity (or blending level) of the annotation. 0 means full transparency, 1 means full opacity.

Allowed float numbers in the range from 0 to 1.

rotationRotationInt

Determines (in °) a rotation of the annotation.

Allowed integers in the range from 0 to 360.

 

Managing annotation presets

Annotation presets are managed directly within the Microsoft SQL database. This section describes how to add, edit, and delete annotation presets. Each operation has its own stored procedure in the ch_librarymanager database.

Each operation in the database should be executed with an active transaction. Only data from successfully executed scripts is applied to the database. The example below describes how to execute a SQL query within a transaction.

BEGIN TRY 
   BEGIN TRANSACTION 
   -- <<< start of query to execute 

   -- write here some query 

   -- >>> end of query to execute 
   COMMIT 
END TRY 
BEGIN CATCH 
   IF @@TRANCOUNT > 0 ROLLBACK TRAN 
   DECLARE @error NVARCHAR(4000) = ERROR_MESSAGE() 
   RAISERROR( @error, 16, 1) 
END CATCH

Stored Procedures

The following are the stored procedures for annotation presets and their allowed parameters.

ch_AddViewerAnnotationPreset

Add an entry to the ViewerAnnotationPresets table.

Param nameTypeIs outputDescription
@annotationTypeIntegerNoAnnotation type ID
@nameStringNoPreset name, max 100 characters
@presetIdIntegerYesReturns ID of created preset

 

ch_SetViewerAnnotationPresetValue

Add or edit annotation preset value (modifies ViewerAnnotationPresetValues table).

Param nameTypeIs outputDescription
@presetIdIntegerNoID of annotation preset of which property should added or modified
@propertyIdStringNoIdentified of the property which should be added or modified
@valueStringNoValue of the annotation property. Regardless of the property type, each value should be written as string
@visibleBooleanNo

Determines whether property should be displayed in UI dialog when adding an annotation preset to the document. If all properties in preset are set to be invisible, an UI dialog when adding annotation will NOT be displayed.

Allowed values:

  • 0 – hide (default value)
  • 1 – show

 

ch_UpdateViewerAnnotationPreset

Update annotation preset name.

Param nameTypeIs outputDescription
@presetIdIntegerNoID of the annotation preset to be modified
@nameStringNoPreset name to be updated

 

ch_RemoveViewerAnnotationPreset

Remove annotation preset from the database.

Param nameTypeIs outputDescription
@presetIdIntegerNoID of the annotation preset to be removed

 

Adding annotation presets

In order to add annotation preset, the following two stored procedures need to be executed:

  • ch_AddViewerAnnotationPreset – Execute only once.
  • ch_SetViewerAnnotationPresetValue – Execute zero or many times - repeat for each property.

Note: Since all default values for each annotation type is stored in the system database, there is no need to duplicate properties with default values in the annotation presets. In another words, annotation presets should consist of only the properties of which values are different that default ones.

For example, adding a rubber stamp annotation preset called “Edited in” that consists of following values:

  • border color: #00FF00
  • text size: 16
  • text color: #00FF00
  • text: “FileHold”
BEGIN TRY 
   BEGIN TRANSACTION 
   -- <<< start of query to execute 
   DECLARE @presetId INT 
   EXEC ch_AddViewerAnnotationPreset 0, 'Edited in', @presetId OUTPUT 
   EXEC ch_SetViewerAnnotationPresetValue @presetId, 'strokeColor', '#00FF00' 
   EXEC ch_SetViewerAnnotationPresetValue @presetId, 'fontSize', '16' 
   EXEC ch_SetViewerAnnotationPresetValue @presetId, 'foreColor', '#00FF00' 
   EXEC ch_SetViewerAnnotationPresetValue @presetId, 'text', 'FileHold' 
   -- >>> end of query to execute 
   COMMIT 
END TRY 
BEGIN CATCH 
   IF @@TRANCOUNT > 0 ROLLBACK TRAN 
   DECLARE @error NVARCHAR(4000) = ERROR_MESSAGE() 
   RAISERROR( @error, 16, 1) 
END CATCH

The stamp would appear as:

Image
Add annotations stamp example

Modifying annotation presets

In order to modify annotation presets, the following two stored procedures need to executed:

  • ch_UpdateViewerAnnotationPreset – zero or once
  • ch_SetViewerAnnotationPresetValue – zero or many times - repeat for each property

For example, changing the name of the annotation preset from “Edited by” to “Edited at” and set following properties:

  • dash style: dash
  • fill color: #FFFFFF
  • text: “[[sys|now|yyyy-MM-dd HH:mm:ss]]” . This dynamic field will be automatically replaced with the current date and time. For a list of available tags, see Assemble document tags.
  • border width: solid (0.08 inch)
BEGIN TRY 
   BEGIN TRANSACTION 
   -- <<< start of query to execute 
   DECLARE @presetId INT 
   SELECT @presetId = PresetId FROM ViewerAnnotationPresets WHERE PresetName like 'Edited in' 
   EXEC ch_UpdateViewerAnnotationPreset @presetId, 'Edited at' 
   EXEC ch_SetViewerAnnotationPresetValue @presetId, 'borderWidth', '0.08' 
   EXEC ch_SetViewerAnnotationPresetValue @presetId, 'dashStyle', '1' 
   EXEC ch_SetViewerAnnotationPresetValue @presetId, 'fill', 'true' 
   EXEC ch_SetViewerAnnotationPresetValue @presetId, 'fillColor', '#FFFFFF' 
   EXEC ch_SetViewerAnnotationPresetValue @presetId, 'text', '[[sys|now|yyyy-MM-dd HH:mm:ss]]' 
   -- >>> end of query to execute 
   COMMIT 
END TRY 
BEGIN CATCH 
   IF @@TRANCOUNT > 0 ROLLBACK TRAN 
   DECLARE @error NVARCHAR(4000) = ERROR_MESSAGE() 
   RAISERROR( @error, 16, 1) 
END CATCH

The stamp would appear as:

Image
Edit annotations preset example

Removing annotation presets

To delete annotation preset, execute following stored procedure:

  • ch_RemoveViewerAnnotationPreset

The example below shows how to delete annotation preset with name “Edited at”. All property values associated with this preset will be removed automatically.

BEGIN TRY 
   BEGIN TRANSACTION 
   -- <<< start of query to execute 
   DECLARE @presetId INT 
   SELECT @presetId = PresetId FROM ViewerAnnotationPresets WHERE PresetName like 'Edited at' 
   EXEC ch_RemoveViewerAnnotationPreset @presetId 
   -- >>> end of query to execute 
   COMMIT 
END TRY 
BEGIN CATCH 
   IF @@TRANCOUNT > 0 ROLLBACK TRAN 
   DECLARE @error NVARCHAR(4000) = ERROR_MESSAGE() 
   RAISERROR( @error, 16, 1) 
END CATCH