ResearchSubscriptionUserDocs < CF

CF Web>ResearchSubscription>ResearchSubscriptionUserDocs (2024-08-27, DanielAllen) (raw view)
---+!! Research Subscriptions User Documentation

%TOC{depth="4"}%

---++ Overview

You can find the application <a href="https://cs.uwaterloo.ca/cscf/research/sub/" target="_blank">here</a>.

---+++ Application Description

The Research Subscriptions application maintains a database of the CSCF [[CSCFResearchSupport][Research Support Group]]'s clients and support subscriptions, generates bills and reports, and interfaces with the [[InventoryUserDocs][Inventory]] and [[https://cs.uwaterloo.ca/cscf/internal/request/][Service Tracking]] applications.

The project is covered by STs and RTs found [[https://cs.uwaterloo.ca/cscf/research/sub/view.php?account=sc-subscriptions][within the subscriptions app]]. ([[https://www.cs.uwaterloo.ca/cscf/internal/request_beta/UpdateRequest?72393][ST#78100]] and its sub-items/see-also) 

---+++ Subscriptions Versus Users

Faculty members and graduate students in the School of Computer Science contract the services of CSCF's Research Support Group (RSG) on a subscription basis.  A subscription represents a purchased number of person-hours of RSG work per term allocated to a group of researchers or to a special project.  The faculty members and students in a group or on a project are 'users' in the Subscription application.  A subscription typically belongs to multiple users and a user may be party to more than one subscription.

Billing for a subscription is allocated among the subscription's users according to a schedule defined in the subscription's record.  A bill is sent to the subscription's faculty contact.

---+++ Types of Subscriptions

There are two types of subscriptions: [[https://cs.uwaterloo.ca/cscf/policies/support.shtml#Desktop%20Support][desktop]] and [[https://cs.uwaterloo.ca/cscf/policies/support.shtml#Dedicated%20Support][dedicated]].  A subscription must be of one type or the other, not both.

   $ Desktop: Service is billed on a per-machine basis.  A subscription enumerates the specific machines that it covers.  Machine data is drawn dynamically from the [[InventoryUserDocs][Inventory]] database.  Support of each included machine costs one desktop unit.  This translates into actual money according to these [[#System_Parameters_By_Term][system parameters]]:%BR%
        <table class="simple">
        <thead>
            <tr>
                <th>Field</th>
                <th>Definition</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Desktop Machine Cost</td>
                <td>Cost of a desktop unit in dollars</td>
            </tr>
            <tr>
                <td>Desktop Units/Hour</td>
                <td>Number of hours of service per term that correspond to one desktop unit.%BR%(Note that the field label is incorrect; it implies the inverse.)</td>
            </tr>
        </tbody>
        </table>

   $ Dedicated: Service is billed on the basis of the person-hours of labour that it is anticipated a subscription will require in a term.  This varies with the needs of the project or group.  The number of units purchased under each subscription is [[#Reviewing_Subscriptions][reviewed]] each term and adjusted for the new term according to usage expectations based on historical usage.  This translates into actual money according to these [[#System_Parameters_By_Term][system parameters]]:%BR%
        <table class="simple">
        <thead>
            <tr>
                <th>Field</th>
                <th>Definition</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Dedicated Unit Cost</td>
                <td>Cost of a dedicated unit in dollars</td>
            </tr>
            <tr>
                <td>Dedicated Units/Hour</td>
                <td>Number of person-hours of service per term that correspond to one dedicated unit.%BR%(Note that the field label is incorrect; it implies the inverse.)</td>
            </tr>
        </tbody>
        </table>

For more information on research computing support policies, see [[https://cs.uwaterloo.ca/cscf/policies/support.shtml#Research_Computing_Support][Computing Support for SCS Faculty and Graduate Students]].

---+++ Who Uses the Research Subscriptions Application?

The application is mainly used by CSCF staff.  They can view and modify all user profiles and subscriptions and have full read and write access.  Faculty can see their own user record and subscriptions, but cannot see billing information and cannot save any changes.

You can find the application's main page <a href="https://cs.uwaterloo.ca/cscf/research/sub/" target="_blank">here</a>.  Log in with your [[http://watiam.uwaterloo.ca/search/][WatIAM]] credentials.  If you follow a link from outside the application, you may have to log in before using the application.

Selected subscription information is also listed at [[https://cs.uwaterloo.ca/cscf/research/contact][Research Points of Contact]].  That list is updated nightly by a batch process.

---++ The Common Page Header

A standard header section appears at the top of every page.

<figure title="Standard page header">
<img id="pageheaderimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/SubscripPageHeader.png" alt="Standard page header" title="Standard page header" />
<figcaption>Figure 1: The standard header at the top of every page in the application</figcaption>
</figure>

The header includes six buttons:

<table class="simple">
    <thead>
        <tr>
            <th>Button</th>
            <th>Function</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Subscriptions</td>
            <td>Return to the Subscriptions Summary page.</td>
        </tr>
        <tr>
            <td>Users</td>
            <td>Maintain users of the subscription application.</td>
        </tr>
        <tr>
            <td>Admin</td>
            <td>Perform administrative functions such as setting unit prices, editing invoice templates, and billing clients.</td>
        </tr>
        <tr>
            <td>Report</td>
            <td>Generate reports.</td>
        </tr>
        <tr>
            <td>Help</td>
            <td>Display the online documentation in a new browser tab.</td>
        </tr>
        <tr>
            <td>Log Out</td>
            <td>Exit from the application.  This will tell you that it has logged you out of the university's [[https://cas.uwaterloo.ca/cas/][Central Authentication Service (CAS)]], but it hasn't.</td>
        </tr>
    </tbody>
</table>

---++ Maintaining Subscriptions

The Subscriptions Summary page lists subscriptions.

<figure title="Subscriptions Summary page of the Research Subscriptions application">
<img id="mainpageimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/SubscripMainPage.png" alt="Subscriptions Summary page of the Research Subscriptions application" title="Subscriptions Summary page of the Research Subscriptions application" />
<figcaption>Figure 2: The Subscriptions Summary page of the Research Subscriptions application</figcaption>
</figure>

You can return to this page at any time by clicking the _Subscriptions_ button in the top-left corner of the page.

---+++ Browsing Subscriptions

By default, all active subscriptions are listed, sorted by subscription code, and presented in pages of 100 subscriptions.

To include inactive subscriptions, uncheck the _Hide Inactive_ checkbox.

To change the number of subscriptions listed on each page, select a number from the _Show [#] entries_ drop-down list.  You can show 10, 25, 50, or 100 subscriptions per page.  Use the buttons in the bottom-right corner of the page to navigate among the pages of listed subscriptions.

To sort the list by a column's data, click the column heading.  To reverse the sorting order, click the column heading again.  To sort by two columns, click the secondary column's heading first and the primary column's heading second.  Subscriptions will then be sorted by the primary column and any items with the same value in the primary column will be sub-sorted by the values in the secondary column.  For example, to sort subscriptions by point of contact and sub-sort by number of Units, most to least, click the _Units_ heading twice and then click the _POC_ heading once.

To restrict the list of subscriptions, enter a search string in the _Search_ box.  As you type, the list will be filtered to show only subscriptions that have your search string somewhere in one of these fields:
   * Subscription
   * Group Name
   * Web Site
   * POC (point of contact)
   * Organizational Unit
   * Comments

Text matching by the filter is case insensitive.

Click the (+) icon at the left of any subscription to toggle a brief display of its details.  Click a link in the _Subscription_ column to see and edit the details of a particular subscription.

---+++ Viewing and Editing a Subscription

At the Subscriptions Summary page, click a link in the _Subscription_ column to see and edit full details.  In the Subscription Details page, you see the full details for a single subscription.

<figure title="Subscription Details page">
<img id="subscripdetailsimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/SubscripDetailsPage.png" alt="Subscription Details page" title="Subscription Details page" />
<figcaption>Figure 3: The Subscription Details page</figcaption>
</figure>

General information is shown on the left.  A term-by-term history of the subscription is shown on the right in a tabbed view, with one tab per term.  The caption on a term's tab consists of a letter representing the season (F = Fall, W = Winter, S = Spring) and the last two digits of the year.  So, for example, a "W15" tab represents the Winter 2015 term.  Each term tab includes a table of [[https://cs.uwaterloo.ca/cscf/internal/request/][Service Tracking]] items billed against the subscription.

To edit a subscription, change details as required and click the _Change Account_ button or the _Change Term_ button, according to where you made a change.  Each _Change_ button saves changes only in its own section of the page.  For field-specific help, click the field's label.  Help will appear in a pop-up window. To view tickets details of a specific term, click the _Show Tickets_ button.

<div class="importantnote">
*Note:* When you make changes in one side of the page, save your changes before you make changes in the other side.  If you make changes in both sides before saving, only the changes made on the side where you click the _Change Account_ or _Change Term_ button will be saved.  Changes on the other side will be discarded as the page is refreshed.
</div>

---++++ Valid Data

   * In the _Faculty_ grid, people in the _Username_ column do not have to be already-registered users in the subscription database.  They can be added on the fly.  Use !WatIAM user ids.
   * A _Point of Contact_ (POC) must already be a registered user in the subscription database.  (See [[#Maintaing_Users][Maintaining Users]], below.)
   * _Dedicated Units Billed_ must be numeric, but may include decimal places (e.g. "4" or "1.75").
   * Faculty (Not Billed), Faculty Contact, Lab Managers, Financial Admins, and Others are !WatIAM usernames separated by commas. Be especially careful with ids in the Faculty grid as they will receive bills.

To view the details of a piece of equipment that is covered by the subscription, click an inventory number in the _Machine Key_ column of the Machines grid.  The [[InventoryUserDocs][Inventory]] system will open to the chosen equipment item in a separate browser tab.

To view the details of a service for which time was charged against the subscription, click a Service Tracking number in the _ST#_ column of the service history grid.  The [[https://cs.uwaterloo.ca/cscf/internal/request/][Service Tracking]] system will open to the chosen item in a separate browser tab.

---+++ Adding a New Subscription

To add a new subscription, follow these steps.

   1. Click the _New_ button in the top-right corner of the Subscriptions Summary page, just below the page header.  A blank subscription template appears.
   1. Fill in details of the subscription.  These fields are required:%BR%
      * [[ResearchSubscriptionFields#Subscription_Code][Subscription Code]]
      * [[ResearchSubscriptionFields#Group_Name][Group Name]]
      * [[ResearchSubscriptionFields#POC][POC]] %BR%
      * If this subscription will be billed, you should also enter one or more [[ResearchSubscriptionFields#Faculty][Faculty]]
.
   1. Click the _Add_ button.

---+++ Deleting a Subscription

You cannot delete a subscription through the web interface.  Instead, flag a subscription as inactive by setting its _Active_ value to "No".  If it should ever be necessary to delete a subscription, a developer could use an SQL command directly against the database instead.

---++ Maintaining Users

To maintain users, click the _Users_ button in the page header.  A Users Summary page appears.

<figure title="Users Summary page of the Research Subscriptions application">
<img id="usersummaryimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/UserSummaryPage.png" alt="Users Summary page of the Research Subscriptions application" title="Users Summary page of the Research Subscriptions application" />
<figcaption>Figure 4: The Users Summary page of the Research Subscriptions application</figcaption>
</figure>

You can return to this page at any time by clicking the _Users_ button in the top-left corner of the page.



---+++ Browsing Users

By default, all users are listed, sorted by _Username_.

To sort the list by a column's data, click the column heading.  To sort by two columns, click the secondary column's heading first and the primary column's heading second.  Users will then be sorted by the primary column and any users with the same value in the primary column will be sub-sorted by the values in the secondary column.

To restrict the list of users, enter a search string in the _Search_ box.  As you type, the list will be filtered to show only users that have your search string somewhere in one of these fields:
   * Username
   * User Comments
   * Expire Date
   * Permissions
   * Real Name

Text matching by the filter is case insensitive.

Click a link in the _Username_ column to see and edit user details.

---+++ Viewing and Editing a User

At the Users Summary page, click a link in the _Username_ column to see and edit user details.  In the User Details page, you see the full details for a single user.

<figure title="User Details page">
<img id="userdetailsimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/UserDetailsPage.png" alt="User Details page" title="User Details page" />
<figcaption>Figure 5: The User Details page</figcaption>
</figure>

The page is divided into three areas:
   * The top-left area shows general information, including user permissions:
      * Faculty can view their own subscriptions with no permissions checked.  Read permission lets one view all users' subscriptions&mdash;not just one's own.  The CSCF help desk user has Read permission.
      * Modify permission allows one to change user and subscription details.
      * School administrative staff who handle payment receipt need Read and Bill permission.
      * Admin permission allows one to alter the application's configuration and perform administrative processes such as reviewing subscriptions and rolling the term.  It also implicitly includes all other permissions.  This is generally limited to RSG staff.
   * The top-right area shows a record of the user's credit transactions and the user's role in various subscriptions.
   * The bottom area has two tabs for financial functions.  See [[#Adjusting_User_Credits][Adjusting User Credits]], below.

---++++ Valid Data

   * Expiry date must be in yyyy-mm-dd format (example: 2017-12-31).  A built-in date picker helps in date selection.

---+++ Adding a New User

To add a new user, follow these steps.

   1. Click the _New_ button in the top-right corner of the Users Summary page, just below the page header.  A blank user template appears.
   1. Fill in the user's details.
   1. Click the _Submit_ button.

---+++ Deleting a User

It is unlikely that you will need to delete a user.  If, for some reason you do need to delete a user, simply click the _Delete User_ button in the top-right corner of the general information area of the User Details page.

---+++ Adjusting User Credits

At the bottom of the User Details page are two tabs for making adjustments to the user's credit.

---++++ Alter Funds

Use this tab to add to, or deduct from, the user's outstanding credit or debt.

---++++ Transfer to Subscription

Use this tab to apply some or all of the user's credit to a particular subscription.

---++++ Valid Data

   * Any monetary amount must be numeric, non-negative, and precise to no more than two decimal places.  Do not include the dollars ("$") sign.  If you need to show a 'negative credit', give a debit.
   * Credit can be transferred to a subscription only if the user is a faculty member.
   * The _Transfer to Subscription_ field takes a valid subscription code that is already and in the database.

---++ Administrative Functions

The application supports the following administrative functions:
   * Configuring system parameters on a term-by-term basis
   * Setting up the up-coming term
   * Reviewing subscriptions
   * Billing clients for their subscriptions
   * Generating spreadsheets for upload to the school's financial system

To find the administrative functions, click the _Admin_ button in the common page header.  The Admin page appears.

<figure title="Admin page of the Research Subscriptions application">
<img id="adminpageimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/AdminPage.png" alt="Admin page of the Research Subscriptions application" title="Admin page of the Research Subscriptions application" />
<figcaption>Figure 6: The Admin page of the Research Subscriptions application</figcaption>
</figure>

---+++ System Parameters By Term

Each tab in the Admin page holds the application configuration parameters for a particular term.  Each tab's label consists of a letter representing a term (F = Fall, W = Winter, S = Spring) and a two-digit year.  For example, "W15" represents "Winter 2015".  Click a tab to select a term.  Parameters are configurable only in the current term.  You can view other terms, but you can't change them.

To save changes to the current term, click the _Change_ button.

---++++ Valid Data

   * Dedicated Unit Cost and Desktop Machine Cost are dollar amounts.  Enter a number, precise to up to two decimal places.  Do not include the dollars sign.
   * Dedicated Units/Hour and Desktop Units/Hour must be numbers.  Decimal places are allowed.  (Note that the field labels are misleading.  These fields define hours per unit, not units per hour.)
   * Dedicated Pagination and Desktop Pagination must be positive integers.
   * Term Comments are in rich text format.  They are for internal information only; they do not appear in bills or reports.
   * Dedicated Template and Desktop Template require valid [[https://www.latex-project.org/][<span class="texhtml" style="font-family: 'CMU Serif', cmr10, LMRoman10-Regular, 'Nimbus Roman No9 L', 'Times New Roman', Times, serif;">L<span style="text-transform: uppercase; font-size: 70%; margin-left: -0.36em; vertical-align: 0.3em; line-height: 0; margin-right: -0.15em;">a</span>T<span style="text-transform: uppercase; margin-left: -0.1667em; vertical-align: -0.5ex; line-height: 0; margin-right: -0.125em;">e</span>X</span>]].

---++++ !LaTeX Templates

_Dedicated Template_ and _Desktop Template_ contain boilerplate text, marked up in [[https://www.latex-project.org/][<span class="texhtml" style="font-family: 'CMU Serif', cmr10, LMRoman10-Regular, 'Nimbus Roman No9 L', 'Times New Roman', Times, serif;">L<span style="text-transform: uppercase; font-size: 70%; margin-left: -0.36em; vertical-align: 0.3em; line-height: 0; margin-right: -0.15em;">a</span>T<span style="text-transform: uppercase; margin-left: -0.1667em; vertical-align: -0.5ex; line-height: 0; margin-right: -0.125em;">e</span>X</span>]], into which values are inserted dynamically during the billing process.

The following placeholder variables, surrounded by double square brackets (&#91;&#91; and &#93;&#93;), will be replaced by the system with subscription-specific and client-specific information.

<table class="simple">
<thead>
    <tr>
        <th>Variable</th>
        <th>Use</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td> ![[term]]</td>
        <td>Shows the term (e.g., "Spring 2015")</td>
    </tr>
    <tr>
        <td> ![[groupname]]</td>
        <td>Shows the subcription's 'group name' (e.g., "AI Group" or "Ali Ghodsi Boushehri")</td>
    </tr>
    <tr>
        <td> ![[units]]</td>
        <td>Shows the count of desktop machines or dedicated units, depending on the subscription type</td>
    </tr>
    <tr>
        <td> ![[unitprice]]</td>
        <td>Shows the price per service unit</td>
    </tr>
    <tr>
        <td> ![[total]]</td>
        <td>Shows the total cost for the term (units &times; unit price)</td>
    </tr>
    <tr>
        <td> ![[dicounts]]</td>
        <td>Shows discount lines (or extra charges)</td>
    </tr>
    <tr>
        <td> ![[balance]]</td>
        <td>Shows the balance after discounts are applied</td>
    </tr>
    <tr>
        <td> ![[facultycontact]]</td>
        <td>Shows name of the subscription's faculty contact</td>
    </tr>
    <tr>
        <td> ![[membercount]]</td>
        <td>Shows the number of users in the subscription</td>
    </tr>
    <tr>
        <td> ![[costperson]]</td>
        <td>Shows the subscription's cost per person</td>
    </tr>
</tbody>
</table>

---+++ Billing

Sometime in the first month of a term, the Manager of Research Support or his designated surrogate needs to perform these tasks:
   1. Roll the Subscriptions application to the new term.
   1. Review subscriptions.
   1. Generate and print bills and send them to school administration.

---++++ Managing subscriptions not to bill

In the subscription view you can set a subscription to have a "Don't Bill" status. Setting a status of "Don't Bill" is useful if you want to exclude certain subscription from being included in the generated bills. When bills are generated and downloaded you will not see the "Don't Bill" subscriptions present in the documents. You also will be unable to generate an individual bill for a subscription that is marked to not be billed. Visibly you will see the "Billing Status" in most tables and in the "Report" section you can filter "Don't Bill" out of the result set shown. 

Despite the difference in status and not appearing in the set of bills, you can track debit and credit charges, and perform all of the other regular functions much like a normal record. Switching back and forth between the two billing statuses is possible by simply switching the status in the subscription view. 

---++++ Rolling the Term

At the Admin page, click the _New Term_ button.  The New Term page shows the name of the current ("Old") term, the name of the new term, a confirmation message text box, and a _Go_ button.

<figure title="New Term page of the Research Subscriptions application">
<img id="newtermpageimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/NewTermPage.png" alt="New Term page of the Research Subscriptions application" title="New Term page of the Research Subscriptions application" />
<figcaption>Figure 7: The New Term page of the Research Subscriptions application</figcaption>
</figure>

To roll to the new term, type the confirmation message displayed on the page into the text box and click the _Go_ button.  The purpose of requiring the confirmation message is to deter accidental rolling of the term, as that would be a non-trivial job to undo.

The process takes several seconds (not "5 minutesish") to complete.  All unpaid charges are carried over to the new term.

---++++ Reviewing Subscriptions

You review subscriptions to ensure that:
   * They are still required in the new term.
   * Desktop subscriptions are assigned the correct machines.
   * Dedicated subscriptions are allocated appropriate numbers of dedicated units, based on past and anticipated service usage.

To review subscriptions, click the _Review_ button in the Admin page.  The Subscription Review page appears.

<figure title="Subscription Review page">
<img id="subscripreviewimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/SubscripReviewPage.png" alt="Subscription Review page" title="Subscription Review page" />
<figcaption>Figure 8: The Subscription Review page</figcaption>
</figure>

The Subscription Review page shows a grid of subscription data with one subscription in each row.

---+++++ Filters

To see only active subscriptions, uncheck the _Hide Inactive_ checkbox.

To include subscriptions that have already been reviewed, uncheck the _Only Unreviewed_ checkbox.  A subscription is considered reviewed if it has text in its _Term Billing Comments_ field.  Comments will be added in the reviewing process described below.

To see only billable subscriptions, check the _Only Billable_ checkbox. 

To see more or fewer subscriptions per page, adjust the _Show [#] entries_ drop-down list to 10, 25, 50, or 100 subscriptions per page.

To filter the list of subscriptions, enter a search string into the _Search_ field.  As you type, the list will be narrowed to include only those subscriptions that have the specified string in one of these fields:
   * Subscription
   * Group Name
   * Web Site
   * POC (point of contact)
   * Organizational Unit
   * Comments

Text matching by the filter is case insensitive.

---+++++ The Reviewing Grid

The Subscription Review page shows a summary of the work purchased and provided for each subscription over the last 3 terms in a grid with one subscription in each row and the following columns:
    <table class="simple">
    <thead>
        <tr>
            <th>Column</th>
            <th>Contents</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>SC</td>
            <td>The subscription code with a link to the subscription details</td>
        </tr>
        <tr>
            <td>Type</td>
            <td>The subscription type (desktop or dedicated)</td>
        </tr>
        <tr>
            <td>New Unit</td>
            <td>A field where you can specify the subscription's number of units for the new term</td>
        </tr>
        <tr>
            <td>Change Unit</td>
            <td>The number of units by which the new term's allocation differs from the previous term's allocation (new minus old)</td>
        </tr>
        <tr>
            <td>U, Hr, E, De</td>
            <td>For each of the previous three terms, a group of four columns:<br />
                <ul>
                    <li>U: Units allocated</li>
                    <li>Hr: Hours actually worked</li>
                    <li>E: Estimated hours (units allocated times configured hours per unit)</li>
                    <li>De: Delta (hours actually worked minus estimated hours)</li>
                </ul>
            </td>
        </tr>
        <tr>
            <td>Average Delta</td>
            <td>The mean of the deltas of the three previous terms</td>
        </tr>
        <tr>
            <td>Billing Status</td>
            <td>The billing status of the subscription
                <ul>
                    <li>Bill</li>
                    <li>Don't Bill</li>
                    <li>Undecided</li>
                </ul>
            </td>
        </tr>
    </tbody>
    </table>

Deltas that represent over-subscription relative to service actually provided appear as negative numbers and are highlighted in red.  A negative delta means either the client is over-subscribed or we're under-serving; a positive delta means we're providing more service than the client subscribes to.  Either way, a large positive or negative delta suggests that a change in the subscription units might be in order, especially if a pattern is emerging across the last three terms.  A global aggregate delta appears at the bottom of the page.

For each dedicated subscription:

   1. Enter a number of units for the new term in the _New Unit_ column.
   1. Open the subscription's _Term Billing Comments_ field by clicking the green (+) button in the left-most column.  Billing comments from the previous three terms are also displayed.%BR%
   <figure title="Term Billing Comments">
   <img id="termbillingcommentsimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/TermBillingComments.png" alt="Term Billing Comments" title="Term Billing Comments" />
   <figcaption>Figure 9: Entering term billing comments</figcaption>
   </figure>
   1. Enter billing comments for the subscription.  The existence of comments indicate that the subscription has been reviewed for the new term.  If you're not making any change for the new term, you might just put "OK" or "No change" in the Term Billing Comments field.  Comments are only for internal reference and may include such things as:
      * what work was done in the previous term
      * observations about the accuracy of past unit allocations
      * expected upcoming projects
      * whether the number of units accurately reflects anticipated work in the new term
      * the rationale for any changes in the number of units or for keeping them the same
   1. Click the _Change Term_ button to save the remarks.

Desktop subscriptions are fairly straight-forward, as they are normally allocated one desktop unit per machine listed in the subscription.  It can be useful to open each desktop subscription by clicking its link in the _SC_ column, look at its Service Tracking history, note the machines involved, and verify that the machines all appear in the subscription's _Machines_ grid.  If a machine is missing from the grid, open its Inventory record by clicking its barcode link in the ST item, go to the Support section, and enter the subscription code in the Inventory record's _Subscription Code_ field.  The Subscription record will be immediately updated but you may need to refresh the browser page.

---++++++ Valid Data

   * Units must be positive numbers and may include decimal places.

---++++ Generating and Printing Bills

When subscriptions have been reviewed, you can generate and print bills for a term _en masse_.  When bills have been printed and distributed, you might get feedback and/or corrections from a client.  If so, you can alter the subscription details and regenerate and reprint an individual bill.

To generate bills, follow these steps.
   1. Click the _Admin_ button in the common header.  The [[#System_Parameters_By_Term][System Parameters]] page appears.
   1. Click the _Billing_ button.  The Billing Summary page appears.
   1. Click the _Generate Bills_ button.  PDF and <span class="texhtml" style="font-family: 'CMU Serif', cmr10, LMRoman10-Regular, 'Nimbus Roman No9 L', 'Times New Roman', Times, serif;">L<span style="text-transform: uppercase; font-size: 70%; margin-left: -0.36em; vertical-align: 0.3em; line-height: 0; margin-right: -0.15em;">a</span>T<span style="text-transform: uppercase; margin-left: -0.1667em; vertical-align: -0.5ex; line-height: 0; margin-right: -0.125em;">e</span>X</span> versions of all of the bills are generated as two large files.  Any subscription that has a billing status of "Don't Bill" will be omitted from the batch.  This step may take several seconds to a minute.

To print bills, follow these stops.
   1. Click the _Admin_ button in the common header.  The [[#System_Parameters_By_Term][System Parameters]] page appears.
   1. Click the _Billing_ button.  The Billing Summary page appears.
   1. Click the _Download Bills_ button.  You are offered a choice of PDF, <span class="texhtml" style="font-family: 'CMU Serif', cmr10, LMRoman10-Regular, 'Nimbus Roman No9 L', 'Times New Roman', Times, serif;">T<span style="text-transform: uppercase; margin-left: -0.1667em; vertical-align: -0.5ex; line-height: 0; margin-right: -0.125em;">E</span>X</span>, or Excel format.  (Excel format does not appear to be working at present.)
   1. Click one of the format icons to select the desired format.  The file is downloaded to your workstation.
   1. Send the file off to printing.  It is formatted for duplex (two-sided) printing, with blank pages as required.
   1. Send the printed bills to the school administration office for distribution to faculty.

A bill looks something like this:

   <figure title="Sample Bill">
   <img id="samplebillimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/SampleBill.png" alt="Sample Bill" title="Sample Bill" />
   <figcaption>Figure 10: Sample bill</figcaption>
   </figure>

To generate and print an individual bill, follow these steps.

   1. Click the _Admin_ button in the common header.  The [[#System_Parameters_By_Term][System Parameters]] page appears.
   1. Click the _Billing_ button.  The Billing Summary page appears.
   1. Locate the relevant subscription and click its link in the _Subscription_ column.  A Billing Details page appears.  This page shows the subscription's complete billing and payment history.
   1. Click the _Generate Bill_ button.  A single bill is generated in both PDF and <span class="texhtml" style="font-family: 'CMU Serif', cmr10, LMRoman10-Regular, 'Nimbus Roman No9 L', 'Times New Roman', Times, serif;">T<span style="text-transform: uppercase; margin-left: -0.1667em; vertical-align: -0.5ex; line-height: 0; margin-right: -0.125em;">E</span>X</span> format.
   1. Click the _Download Bill_ button.  (The button will appear only if a bill has been generated, and even if the amount owed is zero.)  You are offered a choice of PDF, <span class="texhtml" style="font-family: 'CMU Serif', cmr10, LMRoman10-Regular, 'Nimbus Roman No9 L', 'Times New Roman', Times, serif;">T<span style="text-transform: uppercase; margin-left: -0.1667em; vertical-align: -0.5ex; line-height: 0; margin-right: -0.125em;">E</span>X</span>, or Excel format.  (Excel format does not appear to be working at present.)
   1. Click one of the format icons to select the desired format.  The file is downloaded to your workstation.
   1. Send the file off to printing.  It is formatted for duplex (two-sided) printing.
   1. Send the printed bill either to the school administration office or directly to the subscription's faculty contact.
   1. Click the _Back to All_ button to return to the Billing Summary page.

---++++ Adding a Charge

If you need to apply a charge that is outside of the normal subscription formula, follow these steps.

   1. Click the _Admin_ button in the common header.  The [[#System_Parameters_By_Term][System Parameters]] page appears.
   1. Click the _Billing_ button.  The Billing Summary page appears.
   1. Locate the relevant subscription and click its link in the _Subscription_ column.  A Billing Details page appears.
   1. Scroll to the bottom of the Billing Details page.  You'll find a charges and payments area.  If there is no amount owed, you will see only the _Add Charge_ fields.  If an amount is owed, you will see two tabs: one for adding charges and one for receiving payments.%BR%
   <figure title="Adding a Charge">
   <img id="addingachargeimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/AddingACharge.png" alt="Adding a Charge" title="Adding a Charge" />
   <figcaption>Figure 11: Adding a charge</figcaption>
   </figure>
   1. On the Add Charge tab, fill in details (reason, payment method, amount, and comments).
   1. Click the _Submit_ button.  The account is updated and the transaction appears in the bills and payments history, above.

---++++ Receiving a Payment

Receipt of payments is typically handled by school administration.  If you need to receive a payment yourself, follow these steps.
   1. Click the _Admin_ button in the common header.  The [[#System_Parameters_By_Term][System Parameters]] page appears.
   1. Click the _Billing_ button.  The Billing Summary page appears.
   1. Locate the relevant subscription and click its link in the _Subscription_ column.  A Billing Details page appears.
   1. Scroll to the bottom of the Billing Details page.  You'll find a charges and payments area.  If there is no amount owed, you will see only the _Add Charge_ fields.  If an amount is owed, you will see two tabs: one for adding charges and one for receiving payments.%BR%
   <figure title="Receiving a Payment">
   <img id="receivingapaymentimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/ReceivingAPayment.png" alt="Receiving a Payment" title="Receiving a Payment" />
   <figcaption>Figure 12: Receiving a payment</figcaption>
   </figure>
   1. Go to the Pay Bill tab.  There is a field for each user on the subscription.
   1. Fill in the amount that each user is paying.
   1. Click the _Pay_ button.  The account is updated and the transaction appears in the bills and payments history, above.

---+++++ Valid Data

   * All payment amounts must be numeric, positive, and precise to up to two decimal places. If you need to enter a negative credit, choose payment type _debit_ and enter a positive amount).  Up to two decimal places are allowed.
   * The sum of all momentary amounts must equal the total incurred amount.

---++++ FORE

FORE was the accounting system before we switched to Unit4. Please see below for Unit4 details.

---++++ Unit4 Spreadsheet Generator

Unit4 account numbers have the following format: <em>12345 67890-12345 678</em>.

Payment information must be uploaded to the university's Unit4 system.  It's facilitated by a feature of the Research Subscriptions application that generates a spreadsheet that can be uploaded directly to the Unit4 system.  This is normally done by school administration staff rather than by CSCF staff, but the process is described here in broad strokes in case you need to know.

To generate a spreadsheet for Unit4, follow these steps.

   1. Click the _Admin_ button in the common header.  The [[#System_Parameters_By_Term][System Parameters]] page appears.
   1. Click the Unit4 Spreadsheet_ button.  The CSCF Unit4 Spreadsheet Generation page appears.  It shows bills that have been paid through the [[#Receiving_a_Payment][payment receipt]] process.  Generated and/or printed bills that have not yet been paid will not appear.%BR%
   1. Adjust account details as required.
   1. Click the button corresponding to the format in which you want to download payment data.  Unit4 accepts data in either CSV or Excel format. You can safely try all of these options to see what the output looks like. %BR%
      * _Copy_ copies the table data to the system clipboard in a tab-delimited format.
      * _CSV_ exports the data to a simple comma-separated-values (CSV) file.
      * _Excel_ exports the data to a comma-separated-values (CSV) file with some added stuff that makes Excel happier.
      * _Print_ presents the data in your web browser window in a tabular format that you can then print using your web browser's printing feature.
      * _PDF_ saves the data as a Portable Document File (PDF), formatted like an Excel spreadsheet.
   1. Save the file to your workstation's file system.
   1. Upload the file to Unit4.  (This procedure is outside the scope of the Research Subscriptions application.)
   1. *When you are sure* that the data have been successfully received by Unit4, click the _Clear Bills_ button.  This resets the list of paid bills.

---++ Reports

Throughout the term, you can produce reports to monitor how well the group is meeting expectations.  To produce a report, follow these steps.

   1. Click the _Report_ button in the common page header.  A Reports page appears.
   1. Choose how you would like to limit the report's time range.
      * To report on a term, choose a term from the drop-down menu in the _Reporting Term_ field and leave the _Report Start Date_ and _Report End Date_ fields empty.  Terms are bounded by these dates.
        <table class="simple">
        <thead>
            <tr>
                <th>Term</th>
                <th>Starting Date</th>
                <th>Ending Date</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Fall</td>
                <td>September 1</td>
                <td>December 31</td>
            </tr>
            <tr>
                <td>Winter</td>
                <td>January 1</td>
                <td>April 30</td>
            </tr>
            <tr>
                <td>Spring</td>
                <td>May 1</td>
                <td>August 31</td>
            </tr>
        </tbody>
        </table>
      * To report on a custom period of time, choose "Search by Date" in the _Reporting Term_ field's drop-down menu and then specify your starting and ending dates in the _Report Start Date_ and _Report End Date_ fields.  When using this method, both dates are required.  These dates are compared with the dates on which work was done on any ST items associated with the subscriptions.
   1. Choose a report type from the _Report By_ field's drop-down menu.  Your choices are:
      * Subscription Codes
      * POC
      * Person Hours

Reports by subscription code and by point of contact (POC) for a single term display the same information, but group the results differently.
Reports by subscription code group subscriptions into two categories by type: dedicated and desktop.  Reports by point of contact group subscriptions by the primary RSG staff person assigned to the subscription.  When you report on a term, both show these data:

        <table class="simple">
        <thead>
            <tr>
                <th>Column</th>
                <th>Data</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Subscription</td>
                <td>Subscription code with a link to a term-by-term log of tasks</td>
            </tr>
            <tr>
                <td>Type</td>
                <td>Subscription type: dedicated or desktop</td>
            </tr>
            <tr>
                <td>Billing Status</td>
                <td>Bill or Don't Bill</td>
            </tr>
            <tr>
                <td>Hours</td>
                <td>Total hours actually worked in the time period</td>
            </tr>
            <tr>
                <td>Units</td>
                <td>Number of units subscribed</td>
            </tr>
            <tr>
                <td>Exp/Term</td>
                <td>Expected hours of work in the term specified, based on units subscribed</td>
            </tr>
            <tr>
                <td>Var/Term</td>
                <td>Difference ('variance') between actual and expected work hours for the term specified (actual minus expected).<br />Negative amounts indicate fewer hours worked than subscribed and are highlighted in red.</td>
            </tr>
            <tr>
                <td>Exp/Period</td>
                <td>Expected hours of work in the portion of the term up to the current date</td>
            </tr>
            <tr>
                <td>Var/Period</td>
                <td>Difference ('variance') between actual and expected work hours for the portion of the term up to the current date (actual minus expected).<br />Negative amounts indicate fewer hours worked than expected and are highlighted in red.</td>
            </tr>
        </tbody>
        </table>

When you report on a custom time period, you get only subscription code and hours worked, because units and expectations are either not retrievable or not relevant.

Reports by *person hours* group subscriptions by the CSCF staff person who served the client and display these data:

        <table class="simple">
        <thead>
            <tr>
                <th>Column</th>
                <th>Data</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Subscription</td>
                <td>Subscription code</td>
            </tr>
            <tr>
                <td>Hours Worked</td>
                <td>Number of hours worked by this staff person against this subscription</td>
            </tr>
        </tbody>
        </table>

It also shows a total number of hours logged against subscriptions by each staff person in the specific time period.

---+++ Sample Reports

Here is a taste of what the reports look like.

   <figure title="Sample Subscription Codes Report">
   <img id="samplesubscripreportimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/SampleSubscripReport.png" alt="Sample Subscription Codes Report" title="Sample Subscription Codes Report" />
   <figcaption>Figure 14: Sample subscription codes report</figcaption>
   </figure>

   <figure title="Sample Point of Contact Report">
   <img id="samplepocreportimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/SamplePOCReport.png" alt="Sample Point of Contact Report" title="Sample Point of Contact Report" />
   <figcaption>Figure 15: Sample point of contact report</figcaption>
   </figure>

   <figure title="Sample Person Hours Report">
   <img id="samplepersonhoursreportimage" src="https://cs.uwaterloo.ca/twiki/pub/CF/ResearchSubscriptionUserDocs/SamplePersonHoursReport.png" alt="Sample Person Hours Report" title="Sample Person Hours Report" />
   <figcaption>Figure 16: Sample person hours report</figcaption>
   </figure>

<!--
---XX Suggested Workflow

   * When billing period begins, start reviewing and leave comments when items are reviewed.
   * When reviewing is done, go to main billing page and click generate bills.
   * Once bills are generated, go to Download Bills.
   * Download term_bill.pdf and/or manually check over bills in !LaTeX form.
   * Print bills duplex, send bills out.
   * As faculty starts paying up, go to each subscription's page and check the payment scheme. If everything is good, click pay.
   * After all(most) faculty are paid up, go to new term and prepare for next term, any charges added at this point will be charged towards next term's bill.
   * If a subscription has not paid up when the new term is created, the charge will carry over to the next term, and they will be charged for it on next term's bill.
-->

---++ See Also

   * [[ResearchSubscription][Research Subscriptions Web Application]]
   * [[ResearchSubscriptionFields][Research Subscriptions Field Help]]
   * [[ResearchSubscriptionDeveloperDocs][Research Subscriptions Developer Documentation]]

%ADDTOHEAD{"styles" text="
<style type='text/css'>
    figcaption
    {
        font-size: 80%;
        color: #636363;
    }
    div.textarea
    {
        display: inline-block;
        width: 8.0em;
        margin: 0 5px 0 0;
        padding: 0.5em;
        background-color: #F7F7F7;
        border: 2px inset rgba(127,127,127,0.5);
    }
    table.simple
    {
        border-top: 2px solid #D0D0D0;
        border-left: 2px solid #D0D0D0;
        box-shadow: 4px 4px 3px #888888;
    }
    table.simple thead tr th, table.simple tbody tr td
    {
        border-right: 2px solid #D0D0D0;
        border-bottom: 2px solid #D0D0D0;
        border-collapse: collapse;
        border-spacing: 0;
        padding-left: 0.6em;
        padding-right: 0.6em;
        vertical-align: top;
    }
    #receivingapaymentimage
    {
        width: 320px;
    }
    #addingachargeimage
    {
        width: 400px;
    }
    #pageheaderimage
    {
        width: 500px;
    }
    #mainpageimage, #usersummaryimage, #adminpageimage, #newtermpageimage, #samplebillimage, #foregenimage, #samplesubscripreportimage, #samplepocreportimage, #samplepersonhoursreportimage
    {
        width: 600px;
    }
    #subscripdetailsimage, #userdetailsimage
    {
        width: 750px;
    }
    #subscripreviewimage, #termbillingcommentsimage
    {
        width: 900px;
    }
    .importantnote
    {
        border: 1px solid red;
        border-radius: 5px;
        padding: 0.5ex 1em 0.5ex 1em;
        background-color: #FFE0E0;
    }
    .followup
    {
        display: inline-block;
        background-color: #FFDDDD;
        padding: 0 0.6em 0 0.6em;
    }
</style>
"}%
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
png	AddingACharge.png	r1	manage	17.7 K	2015-12-10 - 11:56	JeffGuild	Adding a charge in the Research Subscriptions application
png	AdminPage.png	r1	manage	38.6 K	2015-12-08 - 14:57	JeffGuild	The Administration page of the Research Subscriptions application
png	FORESpreadsheetGeneration.png	r1	manage	49.7 K	2015-12-10 - 12:29	JeffGuild	The CSCF FORE spreadsheet generation page
png	NewTermPage.png	r1	manage	15.9 K	2015-12-08 - 15:51	JeffGuild	The New Term page of the Research Subscriptions application
png	ReceivingAPayment.png	r1	manage	18.9 K	2015-12-10 - 11:57	JeffGuild	Receiving a payment in the Research Subscriptions application
png	SamplePOCReport.png	r1	manage	43.7 K	2015-12-10 - 16:29	JeffGuild	Sample report by point of contact
png	SamplePersonHoursReport.png	r1	manage	34.8 K	2015-12-10 - 16:29	JeffGuild	Sample report by person
png	SampleSubscripReport.png	r1	manage	42.9 K	2015-12-10 - 16:28	JeffGuild	Sample report by subscription code
png	SubscripDetailsPage.png	r1	manage	79.9 K	2015-12-07 - 16:13	JeffGuild	The Details page in the Research Subscriptions application
png	SubscripMainPage.png	r1	manage	81.9 K	2015-12-07 - 13:55	JeffGuild	Main page of the Research Subscription application
png	SubscripPageHeader.png	r1	manage	5.2 K	2015-12-07 - 14:22	JeffGuild	Standard page header in the Research Subscriptions application
png	SubscripReviewPage.png	r1	manage	100.4 K	2015-12-09 - 14:48	JeffGuild	The Subscription Review page of the Research Subscriptions application
png	TermBillingComments.png	r1	manage	45.4 K	2015-12-10 - 09:13	JeffGuild	Term billing comments in the Research Subscriptions application
png	UserDetailsPage.png	r1	manage	46.8 K	2015-12-08 - 09:32	JeffGuild	The User Details page in the Research Subscriptions application
png	UserSummaryPage.png	r1	manage	49.2 K	2015-12-08 - 10:51	JeffGuild	The Users Summary page of the Research Subscriptions application
Topic revision: r41 - 2024-08-27 - DanielAllen
Information in this area is meant for use by CSCF staff and is not official documentation, but anybody who is interested is welcome to use it if they find it useful.
Other Webs
My links
- People
- CERAS
- WatForm
- Tetherless lab
- Ubuntu Main.HowTo
- eDocs
- RGG NE notes
- RGG
- CS infrastructure
- Grad images
Edit