Research Subscriptions User Documentation

Overview

You can find the application here.

Application Description

The Research Subscriptions application maintains a database of the CSCF Research Support Group's clients and support subscriptions, generates bills and reports, and interfaces with the Inventory and Service Tracking applications.

The project is covered by STs and RTs found within the subscriptions app. (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: desktop and 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 Inventory database. Support of each included machine costs one desktop unit. This translates into actual money according to these system parameters:

Field	Definition
Desktop Machine Cost	Cost of a desktop unit in dollars
Desktop Units/Hour	Number of hours of service per term that correspond to one desktop unit. (Note that the field label is incorrect; it implies the inverse.)

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 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:

Field	Definition
Dedicated Unit Cost	Cost of a dedicated unit in dollars
Dedicated Units/Hour	Number of person-hours of service per term that correspond to one dedicated unit. (Note that the field label is incorrect; it implies the inverse.)

For more information on research computing support policies, see 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 here. Log in with your 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 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.

The header includes six buttons:

Button	Function
Subscriptions	Return to the Subscriptions Summary page.
Users	Maintain users of the subscription application.
Admin	Perform administrative functions such as setting unit prices, editing invoice templates, and billing clients.
Report	Generate reports.
Help	Display the online documentation in a new browser tab.
Log Out	Exit from the application. This will tell you that it has logged you out of the university's Central Authentication Service (CAS), but it hasn't.

Maintaining Subscriptions

The Subscriptions Summary page lists subscriptions.

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.

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

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 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 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 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.
2. Fill in details of the subscription. These fields are required:
   
   • Subscription Code
   • Group Name
   • POC
     
   • If this subscription will be billed, you should also enter one or more 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.

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.

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—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, 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.
2. Fill in the user's details.
3. 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.

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

LaTeX Templates

Dedicated Template and Desktop Template contain boilerplate text, marked up in LaTeX, into which values are inserted dynamically during the billing process.

The following placeholder variables, surrounded by double square brackets ([[ and ]]), will be replaced by the system with subscription-specific and client-specific information.

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.
2. Review subscriptions.
3. 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.

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.

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:

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

   

3. 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
4. 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 page appears.
2. Click the Billing button. The Billing Summary page appears.
3. Click the Generate Bills button. PDF and LaTeX 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 page appears.
2. Click the Billing button. The Billing Summary page appears.
3. Click the Download Bills button. You are offered a choice of PDF, TEX, or Excel format. (Excel format does not appear to be working at present.)
4. Click one of the format icons to select the desired format. The file is downloaded to your workstation.
5. Send the file off to printing. It is formatted for duplex (two-sided) printing, with blank pages as required.
6. Send the printed bills to the school administration office for distribution to faculty.

A bill looks something like this:

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

1. Click the Admin button in the common header. The System Parameters page appears.
2. Click the Billing button. The Billing Summary page appears.
3. 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.
4. Click the Generate Bill button. A single bill is generated in both PDF and TEX format.
5. 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, TEX, or Excel format. (Excel format does not appear to be working at present.)
6. Click one of the format icons to select the desired format. The file is downloaded to your workstation.
7. Send the file off to printing. It is formatted for duplex (two-sided) printing.
8. Send the printed bill either to the school administration office or directly to the subscription's faculty contact.
9. 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 page appears.
2. Click the Billing button. The Billing Summary page appears.
3. Locate the relevant subscription and click its link in the Subscription column. A Billing Details page appears.
4. 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.
   

   

5. On the Add Charge tab, fill in details (reason, payment method, amount, and comments).
6. 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 page appears.
2. Click the Billing button. The Billing Summary page appears.
3. Locate the relevant subscription and click its link in the Subscription column. A Billing Details page appears.
4. 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.
   

   

5. Go to the Pay Bill tab. There is a field for each user on the subscription.
6. Fill in the amount that each user is paying.
7. 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 Spreadsheet Generator

Payment information must be uploaded to the university's Financial Online Reporting Environment (FORE). It's facilitated by a feature of the Research Subscriptions application that generates a spreadsheet that can be uploaded directly to the FORE 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 FORE, follow these steps.

1. Click the Admin button in the common header. The System Parameters page appears.
2. Click the FORE Spreadsheet button. The CSCF FORE Spreadsheet Generation page appears. It shows bills that have been paid through the payment receipt process. Generated and/or printed bills that have not yet been paid will not appear.
   

   

3. Adjust account details as required.
4. Click the button corresponding to the format in which you want to download payment data. FORE accepts data in either CSV or Excel format. (We're not sure which.) You can safely try all of these options to see what the output looks like.
   
   • 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.
5. Save the file to your workstation's file system.
6. Upload the file to FORE. (This procedure is outside the scope of the Research Subscriptions application.)
7. When you are sure that the data have been successfully received by FORE, 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.
2. 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.

     Term	Starting Date	Ending Date
     Fall	September 1	December 31
     Winter	January 1	April 30
     Spring	May 1	August 31

   • 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.
3. 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:

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:

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.

See Also

• Research Subscriptions Web Application
• Research Subscriptions Field Help
• Research Subscriptions Developer Documentation