Report Templates 2.0
Posted by Mont Rothstein on 03 December 2013 10:23 AM

This document covers the format of the 2.0 version of Report Templates.  The 2.0 version of report templates was introduced in Adams 4.5.

Overview

Report Templates allow reports to be created or modified and then loaded into Adams.  The reports are then available to run within AdamsWeb.  

Report templates are based on HTML.  The template is standard HTML with special instructions that are interpreted by the report engine.  The special instructions are contained within curly braces {} and square brackets [].  These are called Tokens.

{} - The curly braces contain Report Options.  These tokens tell report engine information about the layout and structure of the report.  Ex: header, footer, page size.

[] - The square brackets tokens tell the report engine what data (text, numbers, dates, images) to place there.  Ex: case number, current date, image.  

Once the report has been generated it is converted into a PDF.  Template => HTML content => PDF

This document will not cover HTML it will only cover the special instructions ({} and [] tokens) interpreted by the report engine.

Tools

Any HTML editor or plain text editor (such as Notepad) can be used.  The Microsoft Visual Studio Express 2013 for Web is free and has a graphical view as well as a source view.

Report Title

The HTML <title> element is read determine the report title.  This is used where the user's selects the report to run and in the report window.

Ex: <title>My Report</title>

Report Option {} Tokens

Parameters

This required token sets general report parameters.  There can be only one of these in a report.

{Parameters      
    ReportOn=""
    SystemReport=""

    PageWidth="8.5"
    PageHeight="11"
    TopMargin="0.25"
    BodyTopMargin="1.25"
    LeftMargin="0.25"
    RightMargin="0.25"
    BodyBottomMargin="0.5"
    Archivable
    Multiple /}

Reports have either a ReportOn or SystemReport parameter.

ReportOn

The ReportOn parameter specifies what type of item the report is for.  The report will be made available to users when an item of the appropriate type is currently selected.

Allowed values:

Asset - The report will be run for the currently selected asset.  If multiple assets are selected then the report will be run once for each selected assets and the results will be combined into a single PDF.

Folder - The report will be run for the currently selected folder.

Property Group - The report will be run for the currently selected property group.

Property Item - The report will be run for the currently selected property item.

Request - The report will be run for the currently selected request.  Request reports must be associated with a specific Request type when they are loaded.

SystemReport

System reports do not run on the current item the user is viewing (Case/Folder, Asset, Property Item, etc.).  Instead they are global reports that can be run at any time and report on multiple items.

Allowed values:

Acquisitions - Assets acquired within a date range. Optionally filtered for cases/folders of a specific type.

AnalysisRequested - Property items which have an analysis type specified.

AuditStatus - Most recent audit entries for property storage locations at or within the selected location.  An optional date will return the audit entries as of that date.

DamagedItems - Audit entries for property items marked as Damaged at or within the selected location.

ExtraItems - Audit entries for property items marked as Extra at or within the location selected.

ItemsByStatus - Property items with the selected status.

LocationsToAudit - Property storage locations at or within the selected location.  Results can optionally be filtered for locations not audited since specified date.  Empty locations can optionally be included.

LocationsWithUnauditedItems - Property storage locations at or within the selected location that have property items which have not been audited.

LostItems - Audit entries for property items marked as Lost within the specified date range.

MissingItems - Audit entries for property items marked as Missing at or within the location selected.

PropertyReceipt - Property Items included in the last change custody action (Drop Off, Receive, Check In, Check Out, Return) during the current session.  This is a special case report that has a ReportOn value of "Changed Custody Property Items" as well as the SystemReport parameter.  It will only run if the current user logged in to AdamsWeb has performed a change custody action during the session.

StaticReport - This is a special value that tells the report engine to generate the PDF without any data (i.e. no case/folder, no assets, etc.).  The report may have components such as header, footer, page number, dimensions, current date, etc.  This is used to provide instructions that users can print out.  Ex: for special barcodes used to perform an audit.

StorageLocations - property item storage locations at or within the selected location.

PageWidth

Optional parameter that specifies the page width in inches.  Default value is 8.5.

PageHeight

Optional parameter that specifies the page height in inches.  Default value is 11.

TopMargin

Optional parameter that specifies the distance from the top edge of the paper to the top of the header in inches.  Default value is 0.25.

BodyTopMargin

Optional parameter that specifies the distance from the top edge of the paper to the top of the report body in inches.  Default value is 1.25.

LeftMargin

Optional parameter that specifies the distance from the left edge of the paper to the left edge of the report in inches.  Default value is 0.25.

RightMargin

Optional parameter that specifies the distance from the right edge of the paper to the right edge of the report in inches.  Default value is 0.25.

BodyBottomMargin

Optional parameter that specifies the distance from the bottom edge of the paper to the bottom of the report body and top of the footer in inches.  Default value is 0.5.

Archivable

Optional parameter that causes the PDF to conform to the PDF/A standard.  This is intended for PDFs that need to be archived for a long period of time.

Multiple

Optional parameter that indicates the report will be processing multiple items instead of only one.  This causes the report to not be repeated once for each item.  This parameter assumes a Section within the report will process the items one at a time.  This is commonly used with System Reports but can also be used for reports that assume multiple items will be selected by the user.  Ex: Contact Sheet report.  See also: the Section Multiple parameter.

Header

{header}
...HTML Content and data tokens...
{/header}

If this optional section is in the HTML body and not within a {Section} then it will appear at the top of each page of the report.

If placed inside of a Section (between a {Section} start tag and {/Section} end tag) then it will appear at the start of the section and will not be repeated if the section is repeated for multiple items (see: Multiple parameter).  

Data tokens in a section Header reference the parent item not the item being processed for the section.  Ex: a report processing a Folder with a Section processing the folder's assets.  A Header in the section will reference the Folder, not the current asset.

Footer

{footer}
...HTML Content and data tokens...
{/footer}

If this optional section is in the HTML body and not within a {Section} then it will appear at the bottom of each page of the report.

If placed inside of a Section (between a {Section} start tag and {/Section} end tag) then it will appear at the end of the section and will not be repeated if the section is repeated for multiple items (see: Multiple parameter).

Data tokens in a section Footer reference the parent item not the item being processed for the section.  Ex: a report processing a Folder with a Section processing the folder's assets.  A Footer in the section will reference the Folder, not the current asset.

Page Number

{page_number}

This optional token can only appear inside of the main report's Header or Footer (not within a Section Header or Footer).  It is replaced by the current page number.  The total number of pages is not available.

Section

A section is an area within a report.  It might simply of a different heading to separate it from the main report or it might process child items of the main item for the report.  Ex: the assets within a folder.  Reports can have multiple sections and sections can be nested.

{Section
    Name=""
    ReportOn="" 
    BatchSize="1"
    ChooseSection
    Multiple
    Optional="Checked"
    Split 
    RequiredPrivilege=""
    PageWidth="8.5"
    PageHeight="11"}

...Section content including {Header}, {Footer}, HTML, data tokens, and nested {Section}...

{/Section}

Name

Optional parameter that specifies a name displayed to the user when they run the report.  Used in conjuction with the Optional and ChooseSection parameters.

ReportOn

Optional parameter that specifies a Field Path or a Request key (see below on Requests and Sub-requests) from the item the parent (section or report body).  The Field Path must lead to one or more items (Assets, Property Items, Requests, etc.) and not to a string, number, date, etc.  This allows a section to process an item or items accessed via the parent.  Ex: if the parent is processing a Folder a section might have ReportOn="Assets" which would process the assets for the folder.  The possible values for this parameter include any valid Field Path that starts with the parent.  These values are unrelated to the value for the report body's ReportOn parameter.

Parameter for Last Path Component

A section's ReportOn Field Path has an additional capability that isn't try for other Field Paths.  The last component of the Path may in some specific instances take a parameter.

Ex: {Section Name=MySection" ReportOn="RequestsOfType='Evidence Received'"}

The above example will pass the 'Evidence Received' parameter to RequestsOfType.  This will in turn only return requests of the given type for the current Folder.

Requests and Sub-requests

If the parent item of the Section is a Request then the value specified in the ReportOn parameter of the Section must be a sub-request Key rather than a Field Path.  The Section will process all sub-requests with the specified Key.  This allows Don't Wait sub-requests, of which there can be multiple, to be processed.  

BatchSize

Optional parameter indicating the number of items to process at a time.  If the section is processing multiple items, either because the ReportOn Field Path returned multiple items or because the Multiple parameter was specified, then items will be processed in chunks equal to the batch size.  This parameter assumes a sub-section will process the items one at a time.

ChooseSection

Optional parameter that requires the user to select one of the sub-sections when running the report.  The sub-sections will be listed by Name.  Ex: used by the Contact Sheet report to let the user choose the number of images to print on a page.

Multiple

Optional parameter that indicates the section will be processing multiple items instead of only one.  This causes the section to not be repeated once for each item.  This parameter assumes a sub-section will process the items one at a time. 

Optional

Indicates the user will be given the option of including the section or not when they run the report.  If a value is specified it can be either "Checked" or "Unchecked".  This indicates if the section will be selected be default or not.  If no value is specified then it will be selected.

Split

Optional parameter that causes a new page to be started after the section.  If the section is processing multiple items then a new page is started after each item is processed.  If the BatchSize parameter is used then a new page is started after each batch.

RequiredPrivilege

Optional parameter that allows an Adams privilege to be specified that the user must have for the section to be included.  Ex: the Folder Details report uses RequiredPrivilege="Access Asset Folder Review" on the "Review" Section.  This insures that users who should not be allowed to view the review notes on a Folder/Case can not include it on a report.

PageWidth

Optional parameter that changes the width of the page.  Useful with the ChooseSection parameter to set the page width based on the section selected by the user.  The value is specified in inches.

PageHeight

Optional parameter that changes the height of the page.  Useful with the ChooseSection parameter to set the page height based on the section selected by the user.  The value is specified in inches.

Report Data [] Tokens

There is a standard token as well as several special token types.  The structure of standard tokens is as follows:

[(Required Type)(Pre HTML)FIELDPATH(Date Format)(Post HTML)]

Note: Contiguous newlines, tabs, and other whitespace within the brackets are compressed into a single space.  This mimics HTML.

Required Type

This is an optional parameter. Allows a data type to be specified that the value must match to be displayed. The format is the keyword "Type¬Ě" followed by a colon and the data type followed by another colon.

TYPE:DATATYPE:

Ex 1: Type:String:
Ex 2: Type:Asset:
Ex 3: Type:Property Item:
If the value returned by the Field Path does not match the specified type then the token is removed and nothing is inserted.

Pre HTML

This is an optional parameter. It allows HTML to be inserted before the token value only if a value exists. The format is raw HTML followed by a vertical bar.

HTML|

Ex 1: <b>My Field Label: </b>|
Ex 2: <h3>My Section Header</h3><b>My Field Label: </b>|

Field Path

This is mandatory. The field path specifies the specific piece of data that will be inserted in the report.  Field paths start from the item the report is being run for and consist of a dot separated path up to and including the field whose value is to be inserted into the report. This can be a field on the item itself, on a related item such as the Folder (case), or on a custom field within a request.
Ex 1: Folder.FolderNumber
Ex 2: Conclusion (if the item being processed is a Request)
Ex 3: @MyStep.MyField (a field within a step on the request being processed)
Ex 4: parent.@MyStep.MyField (a field within a step on the parent request of the request being processed)
Ex 5: child.MySubrequestKey.@MyStep.MyField (a field within a step on the child request specified by the key of the request being processed)
For more information on field paths see: Field Paths and Field Path List.

Date Format

If the field path results in a value that is a date and/or time then an optional date/time format can be specified. The format is a colon followed by the format.

:FORMAT

Ex: :M/d/yyyy
Valid formats can be found here for standard: https://msdn.microsoft.com/en-us/library/az4se3k1(v=vs.110).aspx

Post HTML

This is an optional parameter. It allows HTML to be inserted after the token value only if a value exists.  The format is a vertical bar followed by raw HTML.

|HTML

Ex 1: |<br/>
Ex 2: |<br/><h4>My Sub-section Header</h4>

Special Data Tokens

Image Token

Images are handled differently than other values. The image token must be placed inside of a HTML img element. The image token has its own format.

[Image:FIELDPATH:PARAMETERS]

Ex: [Image:ImageForPrinting:Width=5 Height=6.25 Orientation=MATCH Watermark='Copy']

Image

This is a mandatory key word followed by a colon.

Field Path

This is a standard Field Path as with other tokens but the resulting value must be one of the following:

Asset - either a standard or custom field

Exhibit custom field type resulting in an Asset

Annotation custom field type

Parameters

Width="" Height="" Orientation="" Watermark=""

Width

This optional parameter specifies the maximum width in inches the image will be rendered at or the value "1TO1".

If 1TO1 is specified then the image's width will be calculated based on the number of pixels and resolution.  An attempt to print an un-calibrated image 1TO1 may cause the report to fail to generate.

If no width is specified the maximum width is the PageWidth less the LeftMargin and RightMargin.

Height

This optional parameter specifies the maximum height in inches the image will be rendered at or the value "1TO1".

If 1TO1 is specified then the image's height will be calculated based on the number of pixels and resolution.  An attempt to print an un-calibrated image 1TO1 may cause the report to fail to generate.

If no height is specified the maximum height is the PageHeight less the BodyTopMargin and BodyBottomMargin.

Resolution

This optional parameter specifies the resolution to render that image at in dots per inch (dpi).  The default value is 300.  Ex: 150 or 200. Warning: values above 300 are unlikely to improve the output quality and may result in the report failing if too much memory is used.

This value is distinct from the image's actual resolution which may be used to insure the image prints 1TO1.  An image can both be printed 1TO1 and have this resolution parameter specified.

Orientation

This is optional parameter specifies how an image should be rotated/oriented.

Allowed values are:

Portrait - The image is not rotated.

Landscape - Rotates the image 90 degrees clockwise.

Match - Rotate the image to match the orientation of the 

The default value is Portrait.

Watermark

This optional parameter causes a watermark of the specified text value to be overlayed on the image.  Ex: Watermark="Copy"

CSS Style

The width or height CSS parameter for the <img> element is automatically inserted based on whether the image is wider or taller as rendered.  If this CSS value is already specified inline for the <img> element the report engine will not override the value.  If both width and height are specified inline the image will most likely be distorted (stretched or squished).

For example this: <img src="data:image/jpg;base64,[Image:ImageForPrinting:Width=5 Height=6.25 Orientation=MATCH Watermark='Copy']">

might be rendered as: <img style="width:5in;" src="data:image/jpg;base64,BASE_64_ENCODED_IMAEG_DATA"> 

CurrentUser Token (added in v4.5.3)

A special token that will insert the name of the use current logged in to Adams.

[CurrentUser]

Ex: [CurrentUser]
      John Smith 

Date Token

A special token that will insert the current date and time.  A format for the date/time must be provided as well.

[DATE:FORMAT]

Ex 1: [DATE:M/d/yyyy]
Ex 2: [DATE:M/d/yyyy h:mm:ss tt]

SelectedOptions Token

[SelectedOptions]

A special token that will print any options selected by the user when running the report.  Options that this would show include: date range, optional sections, etc.

Printing Barcodes

The report engine is capable of printing a Code 128 barcode.  This is the same type of barcode used by Adams when it prints property labels.

To print a barcode there are two things the must be done.  The barcode value must be retrieved from an item and CSS styles must be applied to that value.

Barcode Value

The most common barcode to print from Adams would be that of a Property Item.  To print a Property Item's barcode a property item must be the current item being processed either for the report or for a section within the report.  For example, if the report is for a storage location then a section would have ReportOn="PropertyItems" which would cause the section to be processed once for each property item.

Once a Property Item is the item being processed the barcode value must be included in the report.  For a property item the Field Path is UniqueId.  The data token would be:

[UniqueId]

To use a barcode there are JavaScript files that must be included in the HTML report template as well as CSS styles that must be used.  Both are included in the example below.

Barcode Example

This is a simple example of a barcode.  In this instance the barcode value will print below the actual barcode.

<head>

<script type="text/javascript" src="JS/jquery-1.9.1.min.js" ></script>
<script type="text/javascript" src="JS/connectcode-jquery-code128auto.js"></script>
<script type="text/javascript" src="JS/barcodify.js"></script>
<script type="text/javascript">$(document).ready(Barcodify);</script>

<style type="text/css">
.barcode
{

font-weight: normal;            
font-style: normal;             
line-height: normal;             
font-family: 'CCode128_S2', sans-serif;             
font-size: 32px

}
</style>

</head>

<body>

<div class="barcode">[UniqueId]</div>

</body>


Comments (0)