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".

ID

Name

Type

Default value

borderWidth

Border width

Float

0.2

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

fill

Fill

Boolean

False

fillColor

Fill color

String

#000000

stroke

Stroke

Boolean

True

strokeColor

Stroke color

String

#FF0000

fontName

Font name

String

Arial

fontStyle

Font style

Int

1

foreColor

Text color

String

#FF0000

text

Text

String

STAMP

radiusFactor

Radius factor

Float

0.25

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.04

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

fill

Fill

Boolean

False

fillColor

Fill color

String

#FFFFFF

stroke

Stroke

Boolean

True

strokeColor

Stroke color

String

#000000

squaredBox

Squared box

Boolean

False

radiusFactor

Radius factor

Float

0

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

fillColor

Fill color

String

#FFFF00

squaredBox

Squared box

Boolean

False

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.04

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

startCap

Start cap

Int

0

endCap

End cap

Int

0

strokeColor

Stroke color

String

#000000

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

arrowFilled

Arrow filled

Boolean

True

arrowHeight

Arrow height

Int

10

arrowWidth

Arrow width

Int

5

borderWidth

Border width

Float

0.04

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

strokeColor

Stroke color

String

#000000

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.04

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

fill

Fill

Boolean

False

fillColor

Fill color

String

#000000

stroke

Stroke

Boolean

True

strokeColor

Stroke color

String

#000000

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.04

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

fill

Fill

Boolean

False

fillColor

Fill color

String

#FFFFFF

stroke

Stroke

Boolean

True

strokeColor

Stroke color

String

#000000

squaredBox

Squared box

Boolean

False

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.01

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

fill

Fill

Boolean

True

fillColor

Fill color

String

#FFFFFF

stroke

Stroke

Boolean

False

strokeColor

Stroke color

String

#000000

fontName

Font name

String

Arial

fontSize

Font size

Int

12

fontStyle

Font style

Int

0

foreColor

Text color

String

#000000

alignment

Horizontal alignment

Int

0

lineAlignment

Vertical alignment

Int

0

text

Text

String

Text

autoSize

Auto size

Boolean

False

radiusFactor

Radius factor

Float

0

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.01

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

fill

Fill

Boolean

True

fillColor

Fill color

String

#FDFD32

stroke

Stroke

Boolean

True

strokeColor

Stroke color

String

#000000

fontName

Font name

String

Arial

fontSize

Font size

Int

20

fontStyle

Font style

Int

1

foreColor

Text color

String

#000000

alignment

Horizontal alignment

Int

0

lineAlignment

Vertical alignment

Int

0

text

Text

String

Text

autoSize

Auto size

Boolean

False

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.04

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

strokeColor

Stroke color

String

#000000

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.2

strokeColor

Stroke color

String

#FFFF00

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.04

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

strokeColor

Stroke color

String

#000000

fontName

Font name

String

Arial

fontSize

Font size

Int

12

fontStyle

Font style

Int

0

foreColor

Text color

String

#000000

measurementUnit

Measurement unit

Int

1

scale

Scale

Float

1

opacity

Opacity

Float

1

rotation

Rotation

Int

0

ID

Name

Type

Default value

borderWidth

Border width

Float

0.04

dashCap

Dash cap

Int

0

dashStyle

Dash style

Int

0

fill

Fill

Boolean

False

fillColor

Fill color

String

#000000

stroke

Stroke

Boolean

True

strokeColor

Stroke color

String

#000000

fontName

Font name

String

Arial

fontSize

Font size

Int

12

fontStyle

Font style

Int

0

foreColor

Text color

String

#000000

measurementUnit

Measurement unit

Int

1

scale

Scale

Float

1

opacity

Opacity

Float

1

rotation

Rotation

Int

0

 

Annotation property descriptions

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

ID

Name

Type

Description

borderWidth

Border width

Float

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

dashCap

Dash cap

Int

Applicable only when dash style is other than solid.

Allowed values:

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

More details here

dashStyle

Dash style

Int

Allowed values:

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

More details here

startCap

Start cap

Int

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

endCap

End cap

Int

Cap style used at the end of drawn line. Allowed values are the same like for startCap property.

fillColor

Fill color

String

Hexadecimal color code, i.e. #FFFFFF

stroke

Stroke

Boolean

Determines whether a stoke should be visible or not.

Allowed values:

  • True
  • False

strokeColor

Stroke color

String

Hexadecimal color code, i.e. #FFFFFF

fontName

Font name

String

Name of font to be used to render the text

fontSize

Font size

Int

Font size in pixels

fontStyle

Font style

Int

Allowed values:

  • 0 – regular
  • 1 – bold
  • 2 – italic
  • 4 – underline
  • 8 – strikeout

foreColor

Text color

String

Hexadecimal color code, i.e. #FFFFFF

alignment

Horizontal alignment

Int

Allowed values:

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

lineAlignment

Vertical alignment

Int

Allowed values:

  • 0 – top
  • 1 – middle
  • 2 – bottom

text

Text

String

Text value to be displayed as annotation content.

autoSize

Auto size

Boolean

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

Allowed values:

  • True
  • False

squaredBox

Squared box

Boolean

Determines whether annotation should have the same width and height.

Allowed values:

  • True
  • False

radiusFactor

Radius factor

Float

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.

measurementUnit

Measurement unit

Int

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

Allowed values:

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

scale

Scale

Float

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

distance = inches * scale

arrowFilled

Arrow filled

Boolean

Determines whether arrow should be filled or not.

Allowed values:

  • True
  • False

arrowHeight

Arrow height

Int

Determines height of the arrow in inches.

arrowWidth

Arrow width

Int

Determines width of the arrow in inches.

opacity

Opacity

Float

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.

rotation

Rotation

Int

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 name

Type

Is output

Description

@annotationType

Integer

No

Annotation type ID

@name

String

No

Preset name, max 100 characters

@presetId

Integer

Yes

Returns ID of created preset

 

ch_SetViewerAnnotationPresetValue

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

Param name

Type

Is output

Description

@presetId

Integer

No

ID of annotation preset of which property should added or modified

@propertyId

String

No

Identified of the property which should be added or modified

@value

String

No

Value of the annotation property. Regardless of the property type, each value should be written as string

@visible

Boolean

No

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 name

Type

Is output

Description

@presetId

Integer

No

ID of the annotation preset to be modified

@name

String

No

Preset name to be updated

 

ch_RemoveViewerAnnotationPreset

Remove annotation preset from the database.

Param name

Type

Is output

Description

@presetId

Integer

No

ID 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