--- title: "Revenova PayIQ User Guide (TMS 7.12)" slug: "revenova-payiq-user-guide-712" tags: ["7.11", "Admin", "Expanded Content", "7.12"] updated: 2024-10-29T13:55:10Z published: 2024-10-29T13:55:10Z canonical: "documents.revenova.com/revenova-payiq-user-guide-712" --- > ## Documentation Index > Fetch the complete documentation index at: https://documents.revenova.com/llms.txt > Use this file to discover all available pages before exploring further. # Revenova PayIQ User Guide (TMS 7.12) ## **Overview** Revenova PayIQ is an extension module for the Revenova TMS that performs fully automated generation of broker/contractor pay based on the model that is defined in the PayIQ program. All pay calculations and the criteria to determine whether a Load is paid are logged on each Load and Pay record. This allows for auditing of the entire payment process. The Revenova PayIQ package provides the ability to configure and manage: - Who is paid for a Load. - How financial fields are used to determine the amount of pay. - Which Loads are eligible for payment. - When a Load is paid. As a fully-native force.com managed package, Revenova PayIQ seamlessly connects to your CRM environment and takes advantage of all the capabilities within the Salesforce platform. These include mobile support, point-and-click reports and dashboards, anytime/anywhere access, and industry-leading reliability, scalability, and security. ## **Batch Processes/Jobs** Pay is calculated using four separate and linked batch processes. The *Match Loads to PayIQ Participants* job runs first. *Clear Out Unapproved Pay* then runs. Once finished, the *Generate Pay* job runs. Finally, when the *Generate Pay* job completes, the *Match Outside Transactions* job runs. Track the progress of each job in the PayIQ Job Statuses portion of the PayIQ Admin LWC. 1. **Match Loads to PayIQ Participants**: This process matches Loads to PayIQ Programs and verifies that fields defined in the PayIQ Program are set to any eligible Participants (Contacts, Users, or Team Members). Additionally, the PayIQ Program considers the Load Role settings (role of the Participant on the Load) and the eligible Load date to match eligible Loads. If the defined date on the Load falls within the periods defined for that fiscal year, a number of processes occur. - The financial information from freight plans is copied. - Load finances are converted to the org currency for aggregating with other Loads (in multi-currency orgs). - Results are saved into a Participant Match record (the participant identified should be paid on this Load). Participant Match records display in the *org* currency. 2. **Clear Out Unapproved Pay**: This process removes any Load-Participant matches that do not meet criteria for payment. Loads and Participants are available for matching when the Match Loads to PayIQ Participants job runs again in the future. 3. **Generate Pay**: This process takes the Participant Matches generated by the *Match Loads to PayIQ Participants* job and generates a Pay Details record based on the Load filters and calculation tier settings on the Pay Program. Any pay for a Load that is already closed is subtracted from the generated pay. Any Loads with the **PayIQ Locked checkbox** field *Checked* or otherwise do not meet the Load filters defined in the PayIQ Program do not generate pay. 4. **Match Outside Transactions**: This process matches EPayments and Fuel Card Transaction Line Items to Pay Headers generated by the *Generate Pay* job. EPayment **Created Date** and **Deductible** fields determine applicable EPayments. The Fuel Card **Transaction Date** and Fuel Card Transaction Line Item **Deductible** fields determine if a Fuel Card transaction applies. This job creates EPayments and Fuel Card transactions as adjustments on the Pay Header record. 5. **Delete PayIQ Logs**: This optional process deletes log information to free up storage space in the org. ## PayIQ Admin LWC All global settings for PayIQ exist within the PayIQ Admin LWC. A system administrator or Revenova Support should assist with initial setup. The PayIQ Admin LWC consists of four main sections: - PayIQ Jobs Configuration - Delete PayIQ Logs Configuration - PayIQ Job Statuses - Logs ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Admin LWC(1).png) Each section of the PayIQ Admin provides the ability to oversee the creation of payment records. Configure, schedule, and manage PayIQ tasks from the [PayIQ Jobs Configuration](/previous-releases/docs/revenova-payiq-commissions-user-guide#administering-payiq) portion of the LWC. Schedule the jobs or run them manually. Determine how frequently PayIQ logs are deleted in the [Delete PayIQ Logs Configuration](/previous-releases/docs/revenova-payiq-commissions-user-guide#delete-logs) portion. Monitor job activity in the [PayIQ Job Statuses](/previous-releases/docs/revenova-payiq-commissions-user-guide#batch-processes) section of the LWC. Sort and view [Log](/previous-releases/docs/revenova-payiq-commissions-user-guide#administering-payiq) records that provide information on **Definitions** A *PayIQ Program* is the header record that defines a pay structure for a set of users or contacts. A PayIQ Program consists of: - Pay Schedule - Participants - Calculation Tiers The *Pay Schedule* is made up of Pay Periods. A *Pay Period* is an amount of time to match Participants to Loads. A *Participant* is an employee, contractor, or team that matches to Loads. *Participant Matches* occur based on Load Role and customizable Load Filters. The *Calculation Tier* determines the pay brackets for a PayIQ Program. A *Load Filter* is a customizable set of criteria to determine when a Participant matches to a particular Load. A *Pay Detail* is the calculated amount for each Load, for each Participant. Pay Detail records are created based on the Load Filters and Calculation Tiers of the PayIQ Program. ### **PayIQ Jobs Configuration** The PayIQ Jobs Configuration section contains three functions. 1. [Schedule](/previous-releases/docs/revenova-payiq-commissions-user-guide#scheduling-jobs) or immediately perform PayIQ Jobs. The **Execute PayIQ Jobs Now** button runs them immediately. When scheduled, the next run time displays below the Frequency and Time fields. 2. Choose [Logs](/previous-releases/docs/revenova-payiq-commissions-user-guide#logs) to record pay information. 3. Configure [PayIQ batch sizes](/previous-releases/docs/revenova-payiq-commissions-user-guide#batch-size-calculator) for optimal system performance. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Jobs Configuration(3).png) **Batch Sizes** PayIQ job batch sizes may be modified in this section of configuration. The default values are optimal for most orgs. They may be optimized for better performance based on the size of the org. > [!NOTE] > Consult with Revenova Support to determine the optimal settings based on the amount of data the org processes. For more information on configuration and performance, see the [**Performance**](/previous-releases/docs/revenova-payiq-commissions-user-guide#performance) section in [**Troubleshooting PayIQ**](/previous-releases/docs/revenova-payiq-commissions-user-guide#troubleshooting-payiq). ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Batch Sizes(3).png) **Error Email** This email is used to alert Revenova to any unhandled errors when running the PayIQ jobs. Set the Error Email to **customersupport@revenova.com**. Any bugs are automatically escalated and reviewed as bug reports. The **Save** button saves all settings within Configuration Options. This button does ***not*** need to be clicked after scheduling jobs or executing PayIQ jobs now. Job scheduling saves immediately upon selection. ### Delete PayIQ Logs Configuration The Delete PayIQ Logs Configuration section contains three functions. 1. Schedule or immediately delete PayIQ Logs. 2. Choose PayIQ Logs to delete. 3. Select the number of days for deleting PayIQ Logs. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Delete PayIQ Logs Configuration.png) Determine when logs are deleted. 1. Select a *Frequency* from the picklist and a *Time* of day. Options include *Once a Day*, *Twice a Day (every 12 hours)*, *Thrice a Day (every 8 hours)*. 2. *Check* all logs to delete by Category. 3. Click the **Schedule Delete PayIQ Logs** button. Once a schedule is created, the next run time displays below the *Time* field. Manually delete logs by clicking the **Execute Delete PayIQ Logs Now** button. Enter a number of days in the **Delete PayIQ Logs Job Deletes Logs Older than X Days** field. Click **Save**. > [!NOTE] > The **Delete PayIQ Logs Logs Older Than X Days** field follows these rules. > > - 0 deletes all logs. > - 1 deletes logs created **before** the beginning of yesterday. > - The default value is 90 days. > - By default, all log types are *Checked*. View the status of the log deletion job on the PayIQ Job Statuses section. ### PayIQ Job Statuses View detailed status information for each of the four Batch Processes as they perform PayIQ actions. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Job Statuses(1).png) ### Logs The Logs section determines which logs are created when matching Loads to participants, and generating pay. There are five Log types that may be created. > [!NOTE] > To save storage space in an org, Log records are only created once per Load per Log type. Each Log is unique. This means the same message for a Load that doesn’t qualify for all PayIQ Programs for the same reason is only created once. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Logs(1).png) - **Log Performance**: The default option is NOT *Checked*. These logs are not tied to any Loads, or other records. They provide a measurement for package performance. It is strongly recommended to leave these logs off unless troubleshooting with a member of Revenova support. Every time a job is initiated, the following is recorded. - The time to startup. - The time each cycle takes. - The time to complete the job. - **Log Governor Limits**: The default option is NOT *Checked*. These logs are intended for advanced troubleshooting for custom configurations that may cause performance-related errors. It is strongly recommended to leave these logs off unless troubleshooting with a member of Revenova support. Every time a job is initiated, the following is recorded. - The time to startup. - The time each cycle takes. - The time to complete the job. - **Log Qualification (met/did not meet criteria)**: The default option is *Checked*. These logs provide a record of when a user is not paid for a Load. Every time a job is initiated, the following is recorded. - Any criteria NOT met when matching a Load to a participant. - Any criteria NOT met when generating pay. One log record is created. The **Detail** field contains the programs and reasons for not qualifying. - **Log Math**: The default option is *Checked*. These logs provide a record of the calculations made to generate a payment amount. All math logs are in the currency of the org. Every time a job is initiated, the following is recorded. - Every math calculation performed. - **Log Currency Conversions**: This option is only available if multicurrency is enabled. Every time a job is initiated, the following is recorded. - Any instance when a currency is converted. - The exchange rate that was used. For more information on Logs, see the [PayIQ Log Dictionary](/previous-releases/docs/revenova-payiq-commissions-log-dictionary). ## PayIQ Program Setup PayIQ Programs define cascading pay structures that determine how employees and/or contractors are paid. PayIQ Programs are available as a tab within the Salesforce system menu. ![PayIQ - Install 10](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ%20-%20Install%2010.png) Navigate to the PayIQ Programs list to view any existing or to create new Programs. Click **New** to open the PayIQ Program modal and create ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Programs List - New.png) **Initial Fields** To create a new PayIQ Program, provide the following fields. - **Name (required)** - **Pay Schedule (required)** - **Description** (optional) - **Status** **(required, *Pending* is recommended)** ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/New PayIQ Program(1).png) **Status**: Setting the **Status** field initially as *Pending* prevents PayIQ jobs from attempting to run the PayIQ Program. The **Status** field may be changed to *Active* once the program is completed and ready for use to generate pay. ### **Pay Schedule** The **Pay Schedule** field provides the option to select an existing Pay Schedule or to create a new Pay Schedule. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/New Pay Schedule(1).png) Create a new Pay Schedule and provide a description name. Enter an optional Fiscal Year that the Pay Schedule applies to. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/New Pay Schedule - 2.png) It is recommended to create Pay Schedules with **Active** *Checked*. Inactive Pay Schedules are not included when PayIQ jobs run. Click **Save**. ### Pay Periods Once a Pay Schedule record is created, add Pay Periods to it. Click the **New** button to add Pay Periods to a Pay Schedule. > [!NOTE] > Pay Periods must be created for each and every period that falls within the fiscal year. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/New Pay Period.png) To create a new Pay Period, provide the following fields: - **Period Beginning (required)** - **Period Ending (required)** - **Period Status** (*Open* is recommended) - **Payment Due Date** (optional) In the example below, a monthly Pay Period is shown. Pay Periods are flexible based on the payment schedule of the business. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/New Pay Period(1).png) Set the **Period Status** field initially as *Open*. When the PayIQ job runs, *closed* periods are not included. The **Active** field is set accordingly upon Save. Click **Save**. > [!NOTE] > It is recommended to close a Pay Period soon after it is completed. ### Freight Plan Settings > [!WARNING] > For the Freight Plan Load Criteria to function properly, the **FreightPlanManagementJob** must be running. Run or schedule the FreightPlanManagementJob in the TMS with other [batch processes](/previous-releases/docs/batch-processes). Before running the PayIQ jobs make sure the FreightPlanManagementJob has completed. Configure PayIQ Programs with two options to customize how Freight Plan Loads are processed. - **Freight Plan Load Criteria** - **Carrier Load Allocation** **Freight Plan Load Criteria** The Freight Plan Load Criteria picklist sets the completeness criteria for freight plans. Freight Plan Load Criteria includes three options: 1. **—None—**: No criteria are applied. Every freight plan is processed by the PayIQ Program so as long as other criteria are met. 2. **All loads must be quoted**: Every customer Load must have an accepted customer quote, and every Carrier must have an accepted Vendor quote. 3. **All loads must be invoiced**: Every customer Load must have a customer invoice, and every Carrier must have a Vendor invoice. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 16.png) **Carrier Load Allocation** This picklist value determines how to pay Freight Plan Carrier Loads. Carrier Load Allocation criteria includes the following four options. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 17.png) > [!NOTE] > Depending on configuration, Freight Plans may generate multiple Participant Match and Pay Detail records. > > - *Each* ***Customer*** *Load generates 1 Participant Match and 1 Pay Detail records multiplied by the number of eligible Participants.* > - *Each* ***Carrier*** *Load generates Participant Match and Pay Detail records for each applicable Customer Load multiplied by the number of eligible Participants.* > - **Single Customer Load / Multiple Carrier Loads:** 1 Participant Match and 1 Pay Detail records created multiplied by the number of eligible Participants. > - **Single Carrier Load / Multiple Customer Loads:** 1 participant Match and 1 Pay Detail records created for each Customer Load multiplied by the number of eligible Participants. > - **Multiple Carrier Loads / Multiple Customer Loads:** 1 Participant Match and 1 Pay Detail records created for each Customer Load *that the Carrier Load in question covers* multiplied by the number of eligible Participants*.* > > **Example**: *A Freight Plan contains 3 Customer Loads and 2 Carrier Loads.* Customer Load 1 generates 1 Participant Match/Pay Detail records multiplied by the number of eligible Participants. > > Customer Load 2 generates 1 Participant Match/Pay Detail records multiplied by the number of eligible Participants. > > Customer Load 3 generates 1 Participant Match/Pay Detail records multiplied by the number of eligible Participants. > > Carrier Load 1 generates 3 Participant Match/Pay Detail records multiplied by the number of eligible Participants. > > Carrier Load 2 generates 3 Participant Match/Pay Detail records multiplied by the number of eligible Participants. 1. **—None—**: Carrier Loads are not paid. 2. **Cost Contribution**: Carrier Loads are calculated based on the financial cost of each customer Load it covers multiplied by the ratio of the Carrier Load cost / (the customer Load cost + the customer Load cost allocation). $Carrier\ Load\ Margin/Revenue = Customer\ Load\ Margin/Revenue \times Cost\ Contribution\ Ratio = Customer\ Load\ Margin/Revenue \times \left( \frac{Carrier\ Load\ Cost}{Customer\ Load\ Cost + Customer\ Load\ Cost\ Allocation} \right)$ > [!NOTE] > **Freight Plan impact on Cost Contribution Ratio** > > - **Single Customer Load / Multiple Carrier Loads:** Each Carrier Load’s cost contributes a portion of the cost allocation on the Customer Load. This reduces the amount each Carrier Load pays out. from the flat margin/revenue numbers > - **Single Carrier Load / Multiple Customer Loads: :** Each Customer Load's cost allocations contributes a portion of the Carrier Load's cost. This increases the amount each Carrier Load pays out. from the flat margin/revenue numbers > - **Multiple Carrier Loads / Multiple Customer Loads:** Cost contributions depend on how the Carrier/Customer Loads relate to each other and may vary. > > Use Case: Multiple Carriers on the same lane delivering multiple Line Items in the same Delivery. 3. **Distance Contribution**: Carrier Loads are paid based on the financial cost of each customer Load covered multiplied by the ratio of the distance it covers / the distance the customer Load covers. $Carrier\ Load\ Margin/Revenue = Customer\ Load\ Margin/Revenue \times Cost\ Contribution\ Ratio = Customer\ Load\ Margin/Revenue \times \left( \frac{Carrier\ Load\ Distance}{Customer\ Load\ Distance} \right)$ > [!NOTE] > **Freight Plan impact on Distance Contribution Ratio** > > - **Single Customer Load / Multiple Carrier Loads:** Each Carrier Load’s distance contributes a portion of the distance on the Customer Load. This reduces the amount each Carrier Load pays out. from the flat margin/revenue numbers > - **Single Carrier Load / Multiple Customer Loads: :** Each Customer Load's distance contributes a portion of the Carrier Load's cost. This increases the amount each Carrier Load pays out. from the flat margin/revenue numbers > - **Multiple Carrier Loads / Multiple Customer Loads:** Distance contributions depend on how the Carrier/Customer Loads relate to each other and may vary. > > Use Case: When Carrier Loads cover different portions of a Customer Load or a single Carrier covers multiple Customer Load deliveries. 4. **Full**: Carrier Loads are paid on the full financial cost of the Freight Plan as determined by each customer Load covered (regardless of cost or distance contribution). Carrier Load Margin/Revenue = Customer Load Margin/Revenue multiplied by 1. $Carrier\ Load\ Margin/Revenue = Customer\ Load\ Margin/Revenue \times 1$ > [!NOTE] > When **Full** contribution is selected, a Participant Match and Pay Detail records are created for each Customer Load that a Carrier Load covers. ### PayIQ Programs Lightning Record Page Click on a PayIQ Program to view the PayIQ Programs Lightning Record page. This page contains several related lists as well as the ability to *Edit*, *Clone*, or *Delete* the PayIQ Program. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Programs LRP.png) The **Clone** button copies the Participants (Users, Contacts, Teams), Calculation Tiers, Load Roles, and Load filters to the new PayIQ Program. All child objects are copied during the clone process. Cloned programs are named identically to the original PayIQ Program with the addition of a “Clone - “ prefix. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Programs LRP - Clone.png) The **Delete** button removes the PayIQ Program record and all child objects. Participants and Teams do not need to be deleted separately. PayIQ Programs with more than 10,000 participants must be deleted manually. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Programs LRP - Delete.png) ## Participants To include employees and/or contractors in the PayIQ Program, add them as participants. The specific record types of a Participant are either Users or Contacts that must be added to the TMS. Teams are comprised of Users and/or Contacts. See Salesforce documentation for more information on [Users](https://help.salesforce.com/s/articleView?id=sf.admin_users.htm&type=5) and [Contacts](https://help.salesforce.com/s/articleView?id=sf.sales_core_manage_contacts.htm&type=5). ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Programs Participants - New.png) **User Participants** Existing internal employees may be added to the PayIQ Program as Type *User*. Enter and select applicable Salesforce users already created in the org. Add Users to a Team, if necessary. Set an effective and expiration date for the User based on the terms of their employment. Pay is only be calculated for that User if the eligible date calculated from the Load falls within the effective/expiration (inclusive) date range for that User. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 19.png) **Contact Participants** External contractors may be added to the PayIQ Program as type Contact. Type to add external contractors that exist as salesforce contacts to include in the PayIQ Program. Enter and select any Salesforce contact that is already created in the org. Add Contacts to a Team, if necessary. Set an effective and expiration date for the Contract, depending on the terms of the Contact’s contract. Pay is only calculated for a contact if the eligible date calculated from the Load falls within the effective/expiration (inclusive) date range for that Contact. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 20.png) > [!NOTE] > New User and Contact records may be created from the drop-down fields. **Team Participants** Teams are configured as *Participants*. During the *Match Loads to PayIQ Participants* job, matching teams respects the effective and expiration dates for team members. A Team evenly splits pay between the Users and Contacts assigned to that team. Example: A Team has 5 members. If any of the Team members match to a Load, all Team members receive 20% calculated pay. To set up a Team, choose the Participant type *Team*. Enter a descriptive name and click **Save**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 21.png) ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Team Participants - 1.png) Once the Team Participant is created, Users or Contacts are added as members. Click **New** to begin adding members. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 22.png) Members may also be added to Teams on the Participant record. Enter and select the appropriate *Team* field on any Participants. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Team Participants - 2.png) ## Calculation Tiers When all Users and/or Contacts are entered that require a calculated pay, create the pay Calculation Tiers. These tiers define the pay targets, percentages, minimums/maximums, etc. used to calculate pay. Click **New** on the Calculation Tiers related list. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Programs - Calculation Tiers.png)![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Program - Calculation Tier.png) ### Tier Range/Target Tier Ranges/Targets define the criteria to determine whether financials from the Load qualify within the specified range for payout. This section defines pay brackets and/or sales targets to pay. For example: - Tier 1: Pay 10% if the individual Load’s margin is 0 - $100. - Tier 2: Pay 15% if the margin is $100-$200. - Tier 3: Pay 20% if the margin is $200 or higher. **Criteria** This required picklist selects which Load financial information to use as criteria. Each option functions as follows: 1. **Margin** - The criteria is based on the Load margin. 2. **Margin %** - The criteria is based on the Load margin percentage of revenue. 3. **Revenue** - The criteria is based on revenue (Customer Transportation Total). 4. **Load Count** - The number of Loads covered by this participant within the pay period. Freight Plan Loads are counted individually rather than as a unit. This option is always an aggregate count. The following two picklists are disabled when selecting this option (**Financials to Use for Criteria**, **Financial Aggregation Method**). ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 26.png) **Financials to Use for Criteria** Select whether quoted or invoiced financials are used for margin/revenue. This picklist is only applicable for Margin, Margin %, and Revenue-based criteria. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Financials to Use For Criteria.png) **Financial Aggregation Method** The Financial Aggregation Method field allows for two options to determine how pay is calculated. The first calculates the aggregate sum values for margin/revenue. The second calculates each Load’s financial information separately. This dropdown is only applicable for Margin, Margin %, and Revenue-based criteria. The selections function as follows. 1. **Aggregated Load financials per period**: The Generate Pay job performs an aggregate sum of converted Margin/Revenue values for criteria considerations. The aggregate covers the entire Pay Period for the participant considered for pay. The aggregate resets if the Load falls within the next Pay Period. 2. **Individual Load financials (do not aggregate)**: Each Load’s Margin and Revenue is considered on an individual basis. No aggregate sum is performed for criteria. This option emphasizes each Load’s performance rather than the margin over the entire Pay Period. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Financial Aggregation Method.png) **From (>)** This field defines the lower threshold of this tier. Any criteria that falls below this number does ***not*** generate pay unless another tier covers that value. This number is required. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Programs - FROM TO.png) **To (<=)** This field defines the target threshold of this tier, any criteria that exceeds this number does ***not*** generate pay unless another tier covers that value. This number is optional. If blank, the tier is uncapped. ### Tier Calculation Settings This section defines how the final pay calculation is performed to determine the final payout per Load. **Calculation Method** The Calculation Method field determines the type of calculation performed to determine pay. This field is required. Options include: 1. **Amount per Load**: A flat rate payment entered in the Amount field. 2. **Percent of Margin**: The percentage entered to the Margin from the Load. 3. **Percent of Margin with Min**: The percentage entered for the Margin from the Load. A minimum payment based on the Min is entered in the Amount field. 4. **Percent of Margin with Max**: The percentage entered for the Margin from the Load. A maximum payment based on the Max is entered in the Amount field. 5. **Percent of Margin (Sliding Scale)**: The percentage entered for the Margin from the Load. A ratio of Margin/Amount with a maximum set at 1.0. The calculation progressively slides up to the value entered in the Amount field. 6. **Percent of Revenue**: Applies the percentage entered to the Revenue from the Load. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 29.png) **Financials to Use for Calculation** Select Quoted or Invoiced financial information to use for margin/revenue calculations. This picklist only applies to the following calculations. - Percent of Margin - Percent of Margin with Min - Percent of Margin with Max - Percent of Margin (Sliding Scale) - Percent of Revenue based calculations ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 30.png) **Percent** The percentage value used in calculating pay. This field applies to the following calculations: - Percent of Margin - Percent of Margin with Min - Percent of Margin with Max - Percent of Margin (Sliding Scale) - Percent of Revenue ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 31.png) **Amount** The Amount field defines: 1. The Amount value used for Amount per Load calculations. 2. The Min value for Percent of Margin with Min calculations. 3. The Max value for Percent of Margin with Max calculations. 4. The cap value for Percent of Margin (Sliding Scale) calculations. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 32.png) ## Load Roles Load roles define the User or Contact that are paid based on Load fields identifying the individual(s) eligible for the Load. From the PayIQ Program Load Roles related list, click **New**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Programs - Load Roles.png) **Lookup Type** Select the appropriate type in the Lookup Type field. Picklist values include User and Contact. This field is required. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Load Role - Lookup Type.png) **Role Field** The Role Field determines which Load field the User or Contact is selected from. Two User fields, **Carrier Sales Rep** and **Customer Sales Rep** are supported with package installation. One contact field, **Sales Lead (Contact)** is also included with PayIQ. Available options depend on the lookup type selected. Role Field is a global picklist that may be expanded to support additional Load fields. Role Field is required. See [**Custom Load Roles**](/previous-releases/docs/revenova-payiq-commissions-user-guide#custom-load-roles) under the Customizing PayIQ section below to create a custom Load field. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Load Role - Role Field.png) **Eligible Date** The Eligible Date field selects which Load field to use to determine when a Load is eligible for payment. This date determines whether the Load falls within the Pay Schedule for the PayIQ Program. When a Load is matched to a participant, the eligible date also determines if the Load falls within the effective/expiration date for the participants. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Load Role - Eligible Date.png) The Expected Ship Date or Expected Delivery Date are packaged and available to use for the Eligible Date. The **Custom PayIQ Eligible Date** option may be used for supporting other dates. See [**Custom PayIQ Eligible Date**](/previous-releases/docs/revenova-payiq-commissions-user-guide#custom-payiq-eligible-date) under the Customizing PayIQ section below to support a custom date. ## Load Filters PayIQ Programs may not apply to all Loads in the system. Some Loads may be covered by one program and other Loads covered by another. PayIQ provides general-purpose Load Filters for accomplishing this purpose. Add filters by clicking **New** on the Load Filters related list. From the PayIQ Program Load Filters related list, click **New**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Programs - Load Filters.png) Each Load Filter requires three fields to add a filter to the program. 1. Load Field 2. Operator 3. Value **Load Field** The picklist contains all Load fields, including any custom fields (except the OwnerId field). ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 37.png) **Operator** This picklist allows for selecting the operator to apply to the Load field selected above. Each selection functions as follows: - **Equal to**: Straight equality. For multi-picklist fields, the order does not matter. - **Not Equal to**: Straight inequality. For multi-picklist fields, the order does not matter. - **Contains (Text fields only)**: Text must contain the value entered. - **Contains (Multi-picklist fields only)**: The multi-picklist must contain **all** of the multi-picklist selections entered in the value field. - **Equal to Any (Multi-picklist fields only)**: The multi-picklist must contain *any* one of the multi-picklist selections entered in the value field. - **Equal to Any (Picklist and Reference fields only)**: The picklist or lookup must be equal to one of the selections in the list. **Value** The Value field is labeled according to the Load field selected. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 38.png) If the Load field is a picklist or lookup field and the **Equal to Any** operator is selected, add or remove options with the Add/Remove buttons. At least one value must be selected. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Load Filter - Add-Remove.png) ## **Administering PayIQ** **Scheduling Jobs** Scheduling the batch jobs is completed on the PayIQ Admin LWC. It is recommended to schedule the PayIQ jobs to execute automatically unless there is a valid business reason to run them manually. Choose the *Frequency* and *Time* to start running the job from the appropriate section and click the **Schedule PayIQ Jobs** button. The *Frequency* may be set to Once a Day, Twice a Day (every 12 hours), or Thrice a Day (every 8 hours). If the job is already scheduled, the new schedule overrides the previous. Once the PayIQ Jobs have been scheduled to run, the next scheduled time is displayed below the time. > [!NOTE] > - It is recommended to run the PayIQ jobs once a day. > - The Schedule time is always performed in the user time zone that scheduled the jobs. Use caution when businesses operate across multiple time zones as the job schedule impacts when pay records are created. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Jobs Configuration - Schedule(1).png) **Delete Job** Once PayIQ jobs are scheduled, they may be updated to run at any time. Select a different Frequency and/or Time and choose **Schedule PayIQ Jobs**. The PayIQ jobs may also be cancelled. 1. Navigate to **Setup** and search for *Scheduled Jobs*. 2. From the list, find *Match Loads To PayIQ Participants*. 3. Click the *Del* link. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Scheduled Jobs - Cancel.png) **PayIQ On-Demand Execution** To run the PayIQ jobs immediately, click the **Execute PayIQ Jobs Now** button. View the status of each job in the PayIQ Job Statuses section. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Job Status - 1.png) > [!NOTE] > The Job status for each job auto-refreshes every 5 seconds. The columns contain the following information. - **Queued**: Displays the number of iterations prepared for execution. - **Processed**: Displays the number of iterations successfully completed. - **Failures**: Displays the number of iterations that encountered unrecoverable errors. - **Created**: Displays the date and time the job entered into the queue. - **Completed**: Displays the date and time the job completed processing. - **Status**: Displays the current status of the job. - **Details**: Displays any error details encountered due to exceeding governor limits. General unexpected errors are sent to the email address specified in Configuration for bug reporting. Any expected scenarios where a Load might not be paid are saved in the PayIQ logs. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Job Status - 2.png) ### Locking Loads for Payment PayIQ adds a **PayIQ Locked** checkbox field to the Load to exclude Loads from processing. The PayIQ Locked checkbox is located at the bottom of the Load Layout in the PayIQ section. If the field is not available, ensure that the PayIQ Load Page Layout is active and permissions are set appropriately. When *Checked*, the Load is excluded from processing in both the *Match Loads to PayIQ Participants* and *Generate Pay* jobs. Any participant matches/pay details already created on the Load are not impacted. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 44.png) ## **Managing Pay** Review pay numbers to to ensure compensation is correct for the financial information generated. ### Where to Find Pay Numbers There are a number of locations to find how much a participant is paid. **On the Load** If the system admin has enabled the PayIQ Load Page Layout for the organization, the pay information is located on each Load. Navigate to the *PayIQ* tab. If using a custom page layout, add the appropriate related lists as necessary. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 45.png) From the PayIQ tab, view the PayIQ participant and any Pay Details for the Load. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Load Pay Details.png) Click the *Pay Detail* record to view the **Pay Amount** and the Load’s **Calculation Tier**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Load Pay Amount and Calculation Tier.png) Included on the Pay Detail is a reference to the Load financial information used to calculate the Pay Amount. For a multi-currency org, this value is converted to the org’s currency. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Converted Margin Multi-Currency.png) **Pay Headers** A summary of the pay for the current period is located on the Pay Header record. The Pay Header record is a collection of all the Pay Details for a Participant. It represents the payment to the Participant for the Pay Period. View Pay Headers by opening the System Menu and enter *Pay Headers*. The Pay Headers list view is shown below. Pay Header records display amounts in the User or Contact currency. Pay Detail records display values in the User currency. When the PayIQ jobs run, existing Pay Header records are not deleted. The Pay Header records are updated as necessary. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Pay Headers Search.png) Click the *Recently Viewed* dropdown menu and select the *All Pending* list view. Any Pay Headers that are pending payment display in the list. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Pay Headers All Pending.png) Click the Pay Header to view the Pay Details, subtotals, and payroll status. Pay Settlements are also available to print on the Pay Header. Click the **View Pay Settlement** button. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/View Pay Settlement.png) ### Adjustments If an adjustment must be made to the payment for a Participant, add an adjustment to the applicable Pay Header record. Click **New** on the Pay Adjustments related list to add an adjustment. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Pay Adjustments - 2.png) Select the following options to add an adjustment. - **Category**: Addition adds to the pay amount. Deduction subtracts from the pay amount. **(required)** - **Type**: A few common types are listed. When *Other* is selected, a Description may be entered for that adjustment. **(required)** - **Description**: An optional field to describe the type of pay adjustment. - **Transaction Date**: The date for the adjustment. The default value is today. - **Qty**: The number of items for the adjustment. This value is multiplied by the rate to calculate the total. **(required)** - **Rate**: The rate per item. **(required)** - **Receipt Attached**: To attach a receipt, *Check* the box and save the record. Attach an image of the receipt. - **Pay Header**: The Pay Header reference the adjustment is applied to. **(required)** - **Load**: The Load reference the adjustment is applied to. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/New Adjustment.png) **Adjustment Approval** For users with the Approver role, adjust the **Approval Status** using the following fields on the adjustment: - **Status**: The current state of the adjustment approval. Values include *Pending*, *Under Review*, *Approved*, or *Denied*. **(required)** - **Status as of**: The Date and Time of the latest Status change. - **Status Comments**: An optional explanation of the review status. - **Approver**: If the org uses an approval process, set this value to the pay Approver. Approval status does **not** modify numbers on the settlement sheet. Click **Save** when complete. ### EPayments EPayments are added to the appropriate Pay Header by the automated PayIQ process. > [!NOTE] > The *Match Outside Transactions* job only adds EPayments to Pay Headers when the EPayment **Deductible** field is *Checked*. Create a flow or other automation to set this value appropriately. For more information on creating EPayments, see documentation [here](/previous-releases/docs/epayments). ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/EPayments.png) ### Fuel Card Transactions Line Items Fuel Card Transaction Line Items are added to the appropriate Pay Header by the automated PayIQ process. > [!NOTE] > The *Match Outside Transactions* job only adds Fuel Card Transaction Line Items to Pay Headers when the Fuel Card Transaction Line Item **Deductible** field is *Checked*. Manually set the value in the modal shown below. It is also possible to create a flow or other automation to set this value appropriately. For more information on Fuel Cards, see the documentation [here](/previous-releases/docs/fuel-card-management). ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Fuel Card Transaction Line Item - 2.png) ### Pay Settlement To print a Pay Settlement, click the **View Pay Settlement** button in the Pay Header toolbar. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/View Pay Settlement - Button.png) A .PDF document is generated that contains the Pay Details for the Participant for each Load. Any addition or deduction adjustments are included at the end of the document. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Pay Settlement PDF.png) ### Pay Detail - Checking Calculations Confirm financial information by clicking on a **Pay Detail** record. View the PayIQ logs and verify the formula(s) used to calculate the Pay Detail. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Pay Detail - Logs.png) In the example below the logs are filtered to only show Math logs. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Pay Detail - Logs 2.png) Logs include the tier calculation and the math used to calculate the pay. In this example, the invoiced Load margin of $50 multiplied by 10% for a rate of $5 is paid. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ Log - Pay Detail.png) ## **Approving Payment** Complete the pay approval process to close a financial period. This process locks the pay generated by PayIQ. Any future pay generated on the same Loads subtracts any amount already paid. **Pay Approval Process** The pay approval process is completed on the Pay Header record. From the system menu, enter “Pay Headers” to open the Pay Header list view. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 56.png) Select the *All Pending* list view. Click each Pay Header to review any records that require approval. When complete, return to the list view and click the pencil icon for the **Payment Status**. Select *Approved* from the dropdown, and click **Save**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Pay Headers - Pencil.png) ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Pay Headers - Approved.png) The Pay Header is now in an *Approved* status and is fiscally closed out. All applicable Pay Detail records are automatically set to *Approved* by this process. > [!NOTE] > Both the *Approved* and *Paid* statuses function identically. The *Paid* status is for informational purposes to indicate an employee or contractor was sent payment. **Pay Calculation Post Payment Close Out** Pay Calculations may be performed on a Load after closing the payment. This calculation is done on a per-user, per-tier basis. The Pay Calculation is subtracted from the existing Pay Detail records from an *Approved* Pay Header. If the Pay Detail resolves to $0.00, a new Pay Detail record is not generated. When the Pay Detail does not resolve to $0.00, a second Pay Detail record(s) is generated. - If a Participant was under-paid for a load this value is positive. - If the Participant was over-paid this value is negative. Any new Pay Detail record(s) are included on a new Pay Header record. ## **Troubleshooting PayIQ** **Performance** If experiencing trouble with performance, turn on Performance logging using the **Log Performance** checkbox on the PayIQ Admin LWC. Performance logs may be viewed by an administrator in the Logs section of the PayIQ Admin LWC. The past 100 logs may be viewed and filtered. Use *Performance* as Type to view only Performance Logs. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Performance Logs.png) Batch sizes can impact performance dramatically. Consult with Revenova Support for guidance setting values as **high** as the system allows. This type of performance tuning can cause failures and should be completed with the assistance of Revenova Support. The batch size for *Match Outside Transactions* is 2000 and is not configurable. **Batch Size Calculator** Calculate ***estimated*** ideal numbers for batch size performance with the Batch Size Calculator. The Batch Size Calculator is located on the *PayIQ Jobs Configuration* section of the PayIQ Admin LWC. The following factors are considered based on business requirements to achieve optimal system performance. > [!NOTE] > The Batch Size Calculator provides *estimates* to avoid SOQL errors. 1. The maximum number of roles applicable to PayIQ for each Load. 2. The maximum number of cascading programs a Load may qualify for. (1 is common) 3. The maximum number of customer Loads any one Carrier Load covers (Freight Plan size). 4. The maximum number of periods covered each time the Pay Generation job is executed. The PayIQ jobs are recommended to run daily, so the number of periods covered is likely one. 5. The maximum number of tiers per program. 6. The maximum number of members on any team (if using team participants). Set any remaining values to 1. If encountering errors with the Batch Size Calculator, reduce the batch size by half, repeating, until no errors are received. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 60.png) **Governor Limits** Each batch job is designed to avoid Salesforce governor limits. Setting batch sizes too large for the *Match Loads to PayIQ Participants* or *Generate Pay* jobs may result in reaching a governor limit. If a governor limit is reached, the error appears in the **Details** section of each job in the *PayIQ Job Statuses* section of the PayIQ Admin LWC. View performance regarding governor limits by enabling logging on the PayIQ Admin LWC. Set *Log Governor Limits* to *Checked*. Governor Limits logs may be viewed by an administrator in the Logs section of the PayIQ Admin LWC. Governor limit errors are not automatically reported to Revenova. **Unhandled Errors** Any unhandled errors the jobs encounter are sent to the error email defined on the PayIQ Admin LWC. This email address should be set to **customersupport@revenova.com** email so that errors can may be escalated as bug reports. All unhandled errors are treated as bugs in the platform. All expected failure scenarios are intentionally saved as logs. ## **Customizing PayIQ** It is highly recommended to consult Revenova support to customize PayIQ functionality. **Cascading Programs** Multiple participants may be paid different rates on the same Load with cascading programs. Clone or copy all necessary criteria to a second PayIQ program, and set up a different Load Role and percentage to pay. If experiencing difficulty determining the pay structure, contact Revenova Support for assistance. **Custom Load Roles** Create custom Load Roles to enable support for Load Role fields not included in the PayIQ package. Add a Load Role option to be able to select it in a PayIQ Program. 1. Navigate to *Setup*. 2. Select *Object Manager*. 3. Find the *Load Role* object. 4. Click the *Fields & Relationships* link. 5. Choose **Role Field**. 6. Select “View Load Fields Value Set.” ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 61.png) 7. Click **New**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 62.png) 8. Enter the **API Name** of the Load field to support in the entry box and click **Save**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 63.png) 9. Add an optional friendly label by clicking **Edit**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 64.png) 10. Once added, return to *Setup* → *Object Manager* → *Load Role* → *Fields & Relationships*. 11. Select the **Lookup Type** field. Under the *Field Dependency* heading, click **Edit**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 65.png) 12. Determine if the new field is a User or a Contact. In the grid the lookup type is either User or Contact. Click the appropriate grid cell to select it. 13. Choose *Include Values* and click **Save**. The new field is selectable under the lookup type it was added to. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/PayIQ - Install 66.png) **Custom PayIQ Eligible Date** If Loads are to be paid on an eligible date other than **Expected Ship Date** or **Expected Delivery Date**, select **Custom PayIQ Eligible Date** on the Load Role. This is added to the Load object by the PayIQ package as a placeholder field for use by custom-code (a flow, trigger, batch process, or some other means). Please contact Revenova support with your business requirements for assistance in setting up a custom eligible dates. **Set Up Custom Fields as Load Filters** Custom fields are supported as Load filters. Customize logic to determine the pay structures that apply to which Loads. Formula and Boolean type fields are allowed if more complex logic is necessary. Flows, triggers, and batch processes may also update fields used for filtering Loads in PayIQ. Please contact Revenova support with business requirements for assistance in setting up custom Load filters. **Payroll System Integration Settings** The PayIQ Program contains three settings to assist with categorizing pay for payroll system integration. These settings include: - Payroll Description - Payroll Type - Payroll Code These fields are informational and are included in reports that are exported to the external payroll system.