Writing & Using .cis files

Writing & Using .cis Files

I. Writing .cis files

.cis files are used to run a particular script on the CARS database to generate a report, determine access to that report, and display the report as HTML on a web browser. One .cis file performs all of these actions. The Apache perl module CISColby.pm performs all of the data generation/manipulation based on the contents of the .cis file.

To take advantage of the features described in this documentation your file must end with '.cis', such as CWfaccrs.cis (this is true even when running .cis files in debug mode, as described in 'Using .cis Files' below).

These files contain special HTML comment tags that are used to generate, authenticate, and print the HTML-encoded report. These tags can be divided into two separate groups:

CIS tags - used to generate the report, read the data from the report, determine authentication, and special ouput options such as non-HTML mime types and no client-side caching.
Field formatting tags - used to display certain fields of the report, using the .cis file as a template for the HTML output as well as to display browser warnings for browsers which may not full be supported by this HTML report.

A. CIS tags

CIS tags can appear anywhere inside a .cis file (although for convenience you will probably want to keep all of these tags within the <head> and </head> tags of your .cis file. Note that these tags are not send back to the browser when the HTML report is printed.

All CIS tags are of the following format:

such as

The following are the possible attributes and values for a CIS tag and a description of the purpose of that tag:

REPORT GENERATION TAGS: used to generate a report on the CARS system. These tags are required.

Attribute Values Description

SCRIPT Location of a script file relative to kdjlkdj or ksdjflkjds This is the script that will be called to generate the report. Arguments for the script and the order of those arguments are specified using the ORDER CIS tag (see below).

ORDER A comma separated list of names of form inputs, environmental variables, and literal strings that will be used as arguments for SCRIPT (see above). Form names are specified simply with their names, environmental variables are specified as "ENV-[variable name]" and literals are placed within double quotes. For example, <--CIS: ORDER:ENV-REMOTE_USER,sess,"2000"--> would use the environmental variable REMOTE_USER (the username the user authenticated as) for argument 1, the value of the form input named 'sess' as argument 2, and the literal string "2000" as argument 3.

REPORT DATA TAGS: used to read data from a report (reports contain header information on line 1, detail information starting on line 2 and optional footer information on the last line of the report).

Attribute Values Description

HEADER A comma separated list of field names. This list of names will be used by the HEADER and SPECIAL field formatting tags to display header information in the HTML-enabled report (see 'Field Formatting Tags' below).

REPEATED A comma separated list of field names. This list of names will be used by the REPEATED and SPECIAL field formatting tags to display repeated (detail) information in the HTML-enabled report (see 'Field Formatting Tags' below). If missing this report is considered to hold no repeated lines.

FOOTER A comma separated list of field names. This list of names will be used by the FOOTER and SPECIAL field formatting tags to display footer information in the HTML-enabled report (see 'Field Formatting Tags' below). If missing this report is considered to hold no footer line.

AUTHENTICATION TAGS: used to determine if the user (whose login is stored in the environmental variable REMOTE_USER) can view this report). Omit these tags for a report which is viewable by any user.

Attribute Values Description

AUTHFIELDS A comma separated list of header fields whose values will be compared to the login of the user. If the value of one of these fields matches the login of the user, this user will be allowed to view this report.

AUTHUSERS A comma separated list of login names which will be compared to the login of the user. If one of these logins matches the login of the user, this user will be allowed to view this report.

AUTHGROUPS A comma separated list of group names from /etc/group. If the user is in one of these groups, this user will have access to this report.

OUTPUT TAGS: used for special output features of CISColby.pm.

Attribute Values Description

OUTPUT A MIME type for output of this report The MIME type is returned to the browser which, depending on the configuration of the browser, will open the returned file with the appropriate application. If this tag is omitted, the type will be text/html (standard HTML web page).

CACHE NO Forces browsers to not cache the results of this report locally. When this is set to NO the http response header from the server will include an 'Expires' line and a META tag which expires the document immediately will be inserted after the <HEAD> tag (you don't need to include the META tag in your .cis file.

REPORT GENERATION TAGS: used to generate a report on the CARS system. These tags are required.
Attribute	Values	Description
SCRIPT	Location of a script file relative to kdjlkdj or ksdjflkjds	This is the script that will be called to generate the report. Arguments for the script and the order of those arguments are specified using the ORDER CIS tag (see below).
ORDER	A comma separated list of names of form inputs, environmental variables, and literal strings that will be used as arguments for SCRIPT (see above).	Form names are specified simply with their names, environmental variables are specified as "ENV-[variable name]" and literals are placed within double quotes. For example, <--CIS: ORDER:ENV-REMOTE_USER,sess,"2000"--> would use the environmental variable REMOTE_USER (the username the user authenticated as) for argument 1, the value of the form input named 'sess' as argument 2, and the literal string "2000" as argument 3.

REPORT DATA TAGS: used to read data from a report (reports contain header information on line 1, detail information starting on line 2 and optional footer information on the last line of the report).
Attribute	Values	Description
HEADER	A comma separated list of field names.	This list of names will be used by the HEADER and SPECIAL field formatting tags to display header information in the HTML-enabled report (see 'Field Formatting Tags' below).
REPEATED	A comma separated list of field names.	This list of names will be used by the REPEATED and SPECIAL field formatting tags to display repeated (detail) information in the HTML-enabled report (see 'Field Formatting Tags' below). If missing this report is considered to hold no repeated lines.
FOOTER	A comma separated list of field names.	This list of names will be used by the FOOTER and SPECIAL field formatting tags to display footer information in the HTML-enabled report (see 'Field Formatting Tags' below). If missing this report is considered to hold no footer line.

AUTHENTICATION TAGS: used to determine if the user (whose login is stored in the environmental variable REMOTE_USER) can view this report). Omit these tags for a report which is viewable by any user.
Attribute	Values	Description
AUTHFIELDS	A comma separated list of header fields whose values will be compared to the login of the user.	If the value of one of these fields matches the login of the user, this user will be allowed to view this report.
AUTHUSERS	A comma separated list of login names which will be compared to the login of the user.	If one of these logins matches the login of the user, this user will be allowed to view this report.
AUTHGROUPS	A comma separated list of group names from /etc/group.	If the user is in one of these groups, this user will have access to this report.

OUTPUT TAGS: used for special output features of CISColby.pm.
Attribute	Values	Description
OUTPUT	A MIME type for output of this report	The MIME type is returned to the browser which, depending on the configuration of the browser, will open the returned file with the appropriate application. If this tag is omitted, the type will be text/html (standard HTML web page).
CACHE	NO	Forces browsers to not cache the results of this report locally. When this is set to NO the http response header from the server will include an 'Expires' line and a META tag which expires the document immediately will be inserted after the <HEAD> tag (you don't need to include the META tag in your .cis file.

B. Field Formatting Tags

These tags are used to send information from the generated report back to the user. The .cis file acts as the template for the HTML-enabled report. There are several special HTML comment tags that are interpreted by CISColby.pm and converted to HTML:

Tag Format Description

 This tag is converted into the value of the header field 'fieldname' (header field names are determined with the 'HEADER' CIS tag (see 'CIS Tags' above).

 This tag is converted into the value of the form input 'inputname'.

 This tag is converted into the value of the footer field 'fieldname' (footer field names are determined with the 'FOOTER' CIS tag (see 'CIS Tags' above).

 and  Any HTML between these tags will be printed once per line of detail information in the report generated. You may use HEADER, FORM, FOOTER, REPEATED (see below) and SPECIAL (see below) tags in the HTML that appears between these tags.

 This tag is converted into the value of the repeated (detail) field 'fieldname' for the current line of detail being processed (repeated field names are determined with the 'REPEATED' CIS tag (see 'CIS Tags' above). Note that you should only use these tags within <--DETAIL--gt; and <

Tag Format	Description
<!--HEADER:[fieldname]-->	This tag is converted into the value of the header field 'fieldname' (header field names are determined with the 'HEADER' CIS tag (see 'CIS Tags' above).
<!--FORM:[inputname]-->	This tag is converted into the value of the form input 'inputname'.
<!--FOOTER:[fieldname]-->	This tag is converted into the value of the footer field 'fieldname' (footer field names are determined with the 'FOOTER' CIS tag (see 'CIS Tags' above).
<!--DETAIL--> and <!--/DETAIL-->	Any HTML between these tags will be printed once per line of detail information in the report generated. You may use HEADER, FORM, FOOTER, REPEATED (see below) and SPECIAL (see below) tags in the HTML that appears between these tags.
<!--REPEATED:[fieldname]-->	This tag is converted into the value of the repeated (detail) field 'fieldname' for the current line of detail being processed (repeated field names are determined with the 'REPEATED' CIS tag (see 'CIS Tags' above). Note that you should only use these tags within <--DETAIL--gt; and <