How to Setup Usage Collection and Mediation


Step. 1 Setting up the Collector

Billing Platform provides tools for flexible usage collection and mediation. These tools (described below) will allow you to transform raw usage record data (or any other usage data) and map it to the users, products, and components defined the system so that it can be rated and invoiced.

The Usage Collector is the primary tool for mapping data in your usage to users and billable components in the system. The Usage collector can be used to map data in the usage to any system of custom defined field in the system and those fields will be available on invoicing and reporting. The usage collector can also be set to auto‐provision users in the system if it cannot find them based on the mapping. Go to the Setup tab, and select Usage Collectors from the left side menu, you will be show a list of collectors if you have more that one, or the system will automatically select the solitary collector if there is only one.

Usage Collector List

If there is a list of collectors, select new to create a new collector, or edit to change an existing one.

Usage Collector Detail with System and Custom mappings defined

The base attributes for the Usage collector are as follows:

Field Name  Description 
 Collector Name  The Unique Name Identifying the collector. This is helpful if your system needs to collect data from multiple sources.
 Vendor Name  The Vendor or system name identifying the source of the data. 
Collector Type
  • Manual Upload - Choose this option if you will be manually uploading the data into the system.
  • FTP or SFTP - Choose either of these options if you want the system to automatically retrieve usage data files from an FTP site. When this option is selected and multiple usage files are present in the remote server, they will be processed by filename in ascending order.
    This can be configured by a platform developer to behave such that files are sorted by the file creation date instead of the file name. Contact your support resource if this configuration needs to be updated for your org.
  • Web Service - Choose this option if the source of the data is retrieved via a Web Service. 
  • Custom - This option is for custom integration for example, integrating with a proprietary hardware or software application with non‐standard APIs. See Billing Platform Professional Services for more information regarding this option.
 Record Format  Denotes the format that the usage file will support: Current options are “Delimited” and “Fixed”.
 Delimiter  Tells the system how to parse the cells in the file.
 Text Qualifier  A character that surrounds the data between each delimiter. 
 Rows to Skip  Tells the collector how many rows to skip. For example, the header row on a file containing delimited data. 
 Host Name  Used to identify the endpoint (FTP SERVER or Web Service end‐point) from which the data is pulled. 
 Username  User name for logging into the remote service.
 Password  Password supplied for authentication to the remote service.
 Ftp Directory  The directory where files are located on an FTP server. 
After Process Directory The directory where processed files are moved to on the FTP server. This is useful if the processed files need to be retained on the remote server but should be moved to a different directory so that they will no longer be picked up during the next collector checking.
 Ftp File Pattern  Used to only process the files that match the pattern specified.
 Custom Data Management  Custom procedure to be run in conjunction with the collector processing (this customization is only available through Professional Service).
 Rate Collected Activity  Check‐box used to determine if the usage collected will be rated.
 Invoice Collected Activity  Check‐box used to determine if the usage collected should be placed on the invoice. If this is checked then the system will create billable invoices affecting AR.
 Status  Used to take the Collector off‐line. Values are “DEACTIVATED”, “DELETED”,”PRODUCTION”, “TEST” 
 Time Zone  Used to specify the time zone the data is in when collected.

Step 2. Define the Data Mapping for the Collector

There are two types of Data mappings at the collector level: System Mapping, and Custom Mapping. You will be defining how columns/cells in the usage feed map to the data in the system. The screen‐shot above shows how data at specified, numeric positions map to items in the system.

Column Definitions for the System and Custom Mapping are as follows:

  1. FIELD NAME: The name of the system field being mapped 
  2. FIELD POSITION: The Position of the cell or column in the usage file. For example, in the screenshot above, the data in column 7 maps to system field “VENDOR_USER_ID” linking the usage record to the user and associated pricing. Note: A column position can only be used once in the mapping. If there is a need to map the value of a column to different collector fields, consider using a workflow to populate the additional fields.
  3. START POSITION/END POSITION: Used for fixed‐width file formats 
  4. DATE FORMAT: Used to specify the format date values are in so that the system can convert the text into a Date 
  5. FIELD FUNCTION: Function used to transform the data or implement a rule for extraction. 

Step 3. Map the Product Components to the Collector Data

Please see the article on mapping collector data, located here.

Have more questions? Submit a request


  • Avatar
    Abinash John

    What is the difference between "System Mapping Detail" and "Custom Mapping Detail"?

  • Avatar
    Andrew Ryan

    System mapping detail are the system fields that exist in the application out of the box, custom mapping detail are the fields you create in the system, that you can map data to, which can be referenced in reports, invoice, etc.

Powered by Zendesk