Understanding the Contract Maintenance Billing Generator

First available in TMT Fleet Maintenance: 2018.2

As of V.2020.1, this functionality is no longer supported.

If you have the Contract Maintenance module installed, you can use the Contract Maintenance Billing Generator application. It creates invoices for units under active maintenance contracts. The invoices are for monthly billing or fixed and variable costs. They include a billing statement.

The Contract Maintenance Service Contract invoices are billed based upon the customers' billing cycle. These invoices bill the fixed and variable fees based upon the billing cycle and the start and end dates of the service contract.

The billing generator is set up for you as part of your purchased Contract Maintenance module installation.

The information provided here covers:

  • How it is set up

  • How it works

  • How it is tested

It is for reference only.

Do not perform any steps in this topic without contacting Trimble Support first.

How the Contract Maintenance Billing Generator is installed

Trimble installs your Contract Maintenance Billing Generator using this process.

  1. Copies the installation files to the appropriate directory. These files include, but not limited to:

    • TMWSystems.ContractBilling.exe

    • TMWSystems.ContractBilling.exe.config

  2. Edits the TMWSystems.ContractBilling.exe.config ConnectionString to contain your TMT DB connection information.

    Field Description

    Data Source

    serverName

    Initial Catalog

    databaseName

    User ID

    userName

    Password

    password

  3. Edits the TMWSystems.ContractBilling.exe.config appSettings when needed.

    appSetting Default setting Description

    ChargeCategoryFixed

    CMFIXEDCHG

    Charge category for fixed contract charges (level I)

    ChargeCategoryAdditional

    CMADTLCHG

    Charge category for additional contract charges (level II)

    ChargeCategoryVariable

    CMVARCHG

    Charge category for variable contract charges (level II)

    ChargeCategoryPegAtCost

    CMPEGATCOST

    Charge category for variable contract charges (level II)

    SectionComplaint

    PM

    Complaint code used when creating invoice section

    SectionRepairReason

    PM

    Repair reason code used when creating invoice section

    SectionComponentCode

    000

    Component code used when creating invoice section for Level I fixed charges

    SectionComponentCodeKey

    0031

    Code key used when creating invoice section for Level I fixed charges (for example, 0031 corresponds to System level component codes such as 000)

How the Contract Maintenance Billing Generator is scheduled

The billing generator can be run at any time. It generates invoices only as needed. Running the application multiple times does not create duplicate invoices.

As a courtesy, we have provided instructions on using Windows Task Scheduler. The information included here is relevant to using a Windows 10 operating system. Trimble does not track updates to third party applications. If you are using a later version of Microsoft Windows and/or a different operating system, you should consult the vendor’s user documentation for instructions.

To schedule a task:

  1. Click Start.

  2. Type Control Panel.
    The window opens with options for opening the Control Panel.

  3. Click Control Panel app.

  4. Click Administrative Tools.
    The Control Panel window opens.

  5. Double-click Task Scheduler.
    The Task Scheduler window opens.

  6. Find and click the task folder in the console tree where you want to create the task.

  7. In the Actions pane, click Create Basic Task.
    The Create Basic Task wizard opens.

    CMBG Create Basic Task

  8. In the Name field, type a name for the task, such as Contract Maintenance Billing Generator.

  9. In the Description field, type a description for the task, such as Generates invoices for maintenance contracts.

  10. Click Next.
    The Trigger window opens.

  11. Select when you want the task to start. Available options include:

    • Daily (default)

    • Weekly

    • Monthly

    • One time

    • When the computer starts

    • When I log on

    • When a specific event is logged

  12. Click Next.
    The recurrence window opens.

  13. Set the recurrence fields as needed.

    The wizard displays options based on your selected task start. For example, this illustration shows the options available if you select Daily.
    CMBG Task Trigger2

  14. Click Next.
    The Action window opens.

    CMBG Create Basic Task Action

  15. For What action do you want the task to perform?, select Start a program.
    The Start a Program window opens.
    CMBG Create Basic Task Start Program

  16. Complete these fields.

    Field Entry

    Program/script

    Type the location of the TMWSystems.ContractBilling.exe file, such as C:\Program Files (x86)\TMW Systems, Inc\AMS\TMW AMS Contract Maintenance\TMWSystems.ContractBilling.exe.

    Add arguments (optional)

    Leave this field blank.

    Start in

    Type the folder that contains the executable, such as C:\Program Files (x86)\TMW Systems, Inc\AMS\TMW AMS Contract Maintenance\.

    Note: The program uses this information to indicate where relative paths should look relative to this folder. For instance, any logs the program generates are paths relative to this folder.

  17. Click Next.
    The wizard displays a summary of your selections.

    CMBG Create Basic Task Summary

  18. Select Open the Properties dialog for this task when I click Finish.

  19. Click Finish.
    Two things happen:

    • Your changes are saved. Your task will run the next time your selected triggering event happens.

    • The Contract Maintenance Billing Generator Properties (Local Computer) window opens.
      The Settings tab is active by default.
      CMBG Settings Tab

  20. When you are finished reviewing your settings, click OK to close the window.

Understanding how the Contract Maintenance Billing Generator logs events

The application logs events to the targets specified in your TMWSystems.ContractBilling.exe.config file.

This is a sample of the XML code used to define log targets.

<targets>
  <target name="default" xsi:type="File"
     fileName="contract-billing-log.txt"
     archiveFileName="\archives\contract-billing-log.{#}.txt"
     archiveEvery="Day" archiveNumbering="Rolling"
     maxArchiveFiles="90"/>
  <target name="errors" xsi:type="File"
     fileName="contract-billing-errors.txt"
     archiveFileName="\archives\contract-billing-errors.{#}.txt"
     archiveEvery="Day" archiveNumbering="Rolling" maxArchiveFiles="90"/>
  <target name="console" xsi:type="ColoredConsole" layout="${longdate}|${level:uppercase=true}|${logger}|${message}"/>
</targets>

The rules section of the TMWSystems.ContractBilling.exe.config file can be modified as needed. For example, you might want to change the logging level for troubleshooting or to reduce the amount of data logged. The default settings make sure that the default log contains all log messages and that the errors log contain only messages of Error level or higher.

This is a sample of the XML code used to modify the rules section.

<rules>
  <logger name="*" writeTo="console"/>
  <logger name="*" writeTo="default"/>
  <logger name="*" minlevel="Error" writeTo="errors"/>
</rules>

Understanding Contract Maintenance Billing Generator testing

Trimble has identified the scenarios below for use in testing Contract Maintenance Billing Generator.

  1. A bill due percentage greater than 0% means that the application should create an invoice. This percentage is multiplied by the fixed charge amount for Level I contracts to calculate the fixed charge line on the PM section (section 0, component code: 000) for a new invoice.

  2. When testing the application, an extra parameter may be passed to specify the “current date” (today). When this parameter is not passed, the program uses the current date for the bill generation date. When the value is passed, the application uses that date value the bill generation date.

  3. The date value is passed using this syntax: TMWSystems.ContractBilling.exe yyyy/MM/dd. In this syntax, yyyy stands for the four-digit year, MM for the two-digit month, and dd for the two-digit day.

    For example, if the application receives the value TMWSystems.ContractBilling.exe 20XX/10/30 , it runs the billing generation for October 30, 20XX.

Test One: Billing recurs on the first of the month

Scenario Start Bill Date Last Bill Date Current Date (“Today”) Bill Due %

NeverBeenBilled
TodayAfterBillDate

08/01/20XX

09/02/20XX

203.333 %

NeverBeenBilled
TodayBeforeBillDate

10/01/20XX

09/19/20XX

000.000 %

NeverBeenBilled
TodayEqualsStartBillDate
HasProRated

08/31/20XX

09/01/20XX

103.333 %

NeverBeenBilled
TodayEqualsStartBillDate
NoProRated

09/01/20XX

09/01/20XX

100.000 %

PreviouslyBilled
TodayAfterBillDate
CurrentCycle

09/02/20XX

09/01/20XX

09/19/20XX

000.000 %

PreviouslyBilled
TodayAfterBillDateSkippedInvoicePriorMonth

04/01/20XX

07/01/20XX

09/19/20XX

200.000 %

PreviouslyBilled
01TodayBeforeBillDate

05/01/20XX

09/01/20XX

09/02/20XX

000.000 %

PreviouslyBilled
TodayEqualsLastBillDate

09/01/20XX

09/01/20XX

09/01/20XX

000.000 %

Test Two: Billing recurs on the fifteenth of the month

Scenario Start Bill Date Last Bill Date Current Date (“Today”) Bill Due %

NeverBeenBilled
TodayAfterBillDate

08/30/20XX

10/01/20XX

203.333 %

NeverBeenBilled
TodayBeforeBillDate

10/30/20XX

09/19/20XX

000.000 %

NeverBeenBilled
TodayEqualsStartBillDate
HasProRated

10/13/20XX

10/31/20XX

160.000 %

NeverBeenBilled
TodayEqualsStartBillDate
NoProRated

09/30/20XX

09/30/20XX

100.000 %

PreviouslyBilled
TodayAfterBillDate
CurrentCycle

10/01/20XX

09/30/20XX

09/19/20XX

000.000 %

PreviouslyBilled
TodayAfterBillDate
SkippedInvoicePriorMonth

04/30/20XX

07/30/20XX

09/19/20XX

200.000 %

PreviouslyBilled
TodayBeforeBillDate

05/30/20XX

09/30/20XX

10/01/20XX

000.000 %

PreviouslyBilled
TodayEqualsLastBillDate

09/30/20XX

09/30/20XX

09/30/20XX

000.000 %

Test Three: Billing recurs on the end of the month

Scenario Start Bill Date Last Bill Date Current Date (“Today”) Bill Due %

NeverBeenBilled
TodayAfterBillDate

08/30/20XX

10/01/20XX

203.333 %

NeverBeenBilled
TodayBeforeBillDate

10/30/20XX

09/19/20XX

000.000 %

NeverBeenBilled
TodayEqualsStartBillDate
HasProRated

10/13/20XX

10/31/20XX

160.000 %

NeverBeenBilled
TodayEqualsStartBillDate
NoProRated

09/30/20XX

09/30/20XX

100.000 %

PreviouslyBilled
TodayAfterBillDate
CurrentCycle

10/01/20XX

09/30/20XX

09/19/20XX

000.000 %

PreviouslyBilled
TodayAfterBillDate
SkippedInvoicePriorMonth

04/30/20XX

07/30/20XX

09/19/20XX

200.000 %

PreviouslyBilled
TodayBeforeBillDate

05/30/20XX

09/30/20XX

10/01/20XX

000.000 %

PreviouslyBilled
TodayEqualsLastBillDate

09/30/20XX

09/30/20XX

09/30/20XX

000.000 %

Accounting

Disbursement rules must be added for each of the charge categories to route the charges to accounts properly.