Mediation

Mediation adds a simple user interface to streamline data mediation which can be a critical part of the billing process. It allows you to easily convert your usage data into Gotransverse’s usage data format where the data can be accepted by GTV’s rating sytem, then, later be consumed during regular rating (converted into pricing) and billing (added to customers’ accounts and invoices) processes.

You accomplish this by creating and running mediation jobs. You can view data records during or after job runs to identify and troubleshoot failures. You also have the option to edit or delete jobs.

Mediation Phases

Jobs you create run through a mediation process which consists of the following phases:

Field Description
Import Your raw usage data file is imported into the Mediation application.
Normalization Usage data is normalized, meaning raw data is converted to a standardized table format so it can be processed during the mediation phase.
Mediation The application performs business logic on the normalized usage data, including executing complex rules, to convert the normalized data to a format that can be accepted by GTV’s rating system.
Mediated data records are tagged either as successful or failed. Failed records are further categorized as Failure due to error or Filtered due to a complex rule that filtered records as part of business logic.

Note: Mediation can take a single usage record in your file and convert it into more than one mediated record, if needed. For example, if there’s a usage record with multiple SRIDs, mediation can convert the record into a mediated record for each SRID.

Rating Successfully mediated data records are sent for rating engine acceptance. Rated records are tagged as either successful or failed.

Complex Rules

GTV support can collaborate with you in adding complex rules (business logic) to transform and filter data for accuracy in rating and billing. You can manipulate data and filter records based on rules as well as have rules refer to usage lookup tables to drive business logic.

You can do things like:

  • Filter out individual line items based on defined rules. For example, filter out any records where COLUMN_A > 10.
  • Throw an error for records unaccounted for by defined rules. For example, if COLUMN_B !=’A’ or ’B’, throw an error.
  • Manipulate records through defined rules. For example, if COLUMN_B==’A’, then multiply COLUMN_C by 2.
  • Refer to usage lookup tables for defined rules. For example, take the value from COLUMN_A and match to the key in ‘Usage Table1’, then replace with the value from the lookup table.

After a job runs or pauses for approval, you can view whether a record was labeled Failure or Filtered in the Mediation Failed tab.

Records are labeled Failure for one of the following reasons:

  • Data type error. For example, the record has a field that’s expected to be an integer, but contains a string.
  • A complex rule error. For example, a rule to look up a field value in a lookup table, then perform an action based on that, but the value doesn’t match any information in the lookup table.

Records are labeled Filtered because a rule caused the record to be filtered out. For example, a rule is added to mediate records with a value of ‘A’ in Text_01, but to filter records with a value of ‘B’ in Text_01.

Setup Overview

Mediation setup includes:

  1. Initial mediation setup by Gotransverse support.
  2. Adding a raw usage data file to an S3 bucket or sFTP website you supply for import into the GTV platform. Delimited text files are supported.
  3. Creating a mediation job.
  4. Running a mediation job on a schedule or manually.
  5. Optionally, pausing a job run after files are mediated (before sending to rating), reviewing data records, then, either approving the mediated results and resuming the job or cancelling the job. The job pauses only if it’s been configured to pause.
  6. Viewing the job run results for the completed job run in real time, including success or faiure of rating acceptance.

You can also edit or delete an existing mediation job.

Creating a Mediation Job

After initial mediation setup by GTV and usage data file setup, you can create a mediation job.

  1. Select Mediation from the Gotransverse action menu .
  2. Select Setup in the left pane. The Setup page displays a list of created mediation jobs.
  3. Click Create System Job from the Setup action menu.
  4. Complete the relevant fields for the job in the Create System Job window:
    FieldDescription
    Job Name*Enter a name for your mediation job.
    Status*

    Select one of the following statuses for your job:

    • Active—The job will run according to its scheduled or manual job run.
    • Paused—The job will not run according to its scheduled run. If the job is run manually, it will be rejected.
    DescriptionEnter a description for the job.
    EmailsEnter an email address of the individual you want to notify when a job run completes.
    Add EmailsClick to add an additional email address for notification of job run completion.
    Run Interval (Cron)

    Enter information in cron format to run the job at a scheduled time. Alternatively, you can run the job manually through the Run Manager page in Mediation.

    The standard cron format consists of five fields separated by white spaces: <Minute> <Hour> <Day_of_the_month> <Month_of_the_year> <Day_of_the_Week>. For example, 0 9 1 * * runs the job on the first day of each month, at 9am.

    Type*Select Gotransverse Usage Mediation from the drop-down menu.
    Usage Stream*Select a pre-populated product line (stream) from the drop-down menu.
    Data Source*

    Select either sFTP or S3 to connect GTV to the source where your usage data file is stored. Based on the option you select, the following fields display:

    • sFTP—Data server that will securely store and transfer your files to the GTV platform.
      • sFTP Host*—Enter the host name of your sFTP, for example, gasenergy.exvault.com.
      • sFTP Port*—Enter the port number of your sFTP, for example, 20.
      • sFTP Username—Enter the user name of your sFTP, for example, dasriC0!.
      • Authentication Method*—Select the authentication mode that GTV will use to access your sFTP.
        • Key-Pair—Select to allow for a GTV-generated private key authentication to connect to your sFTP.
        • Password—Select to use your sFTP password for authentication.
          • sFTP Password*—Enter your sFTP password.
    • S3—Data server hosted by Amazon Web Services (AWS) that will securely store and transfer your files to the GTV platform.
      • S3 Bucket Name*—Enter your S3 bucket name, for example, Acme.
      • AWS Access Key ID*—Enter your access key ID provided by AWS.
      • AWS Secret Key Access*—Enter your secret access key provided by AWS.
      • AWS Region Name*—Enter your secret access key provided by AWS.
    Source PathEnter the source file path for the file sFTP or S3 environment where the data file resides. For example, /product/mks/mediaton/usage-files.
    Source file Name*Enter the source file name, for example, MD8-Usage-File.txt.
    Requires User Confirmation of Mediated Data Before Rating?Select one of the following options to determine whether or not a running job will pause after the mediation phase and require approval before moving to the rating acceptance phase of the job run:
    • Always—Job run always pauses and requires approval even if there are no mediated errors.
    • Only When Errors are Present—Job run pauses and requires approval only when there are mediated errors.
    • Never—Job run does not pause or require approval. Successfully mediated data moves directly to rating approval. This is the default behavior.

    When a job is paused, you have the option to either approve or cancel the job.

    *Indicates required field.

  5. Click Create.

Your job is added to the mediation job list on the Setup page. If the job is in Active Status and you configured the Run Interval (Cron) field during job creation, your job is set to run at the indicated interval. Otherwise, you can run an Active job manually.

Running a Mediation Job Manually

After you create a job, you have the option to create and execute a manual job run. The job you run must be in Active status. If the job is in Paused status, the job will be rejected when you try to run it manually.

  1. Select Mediation from the Gotransverse action menu . The Run Manager page displays. The page includes a list of already run mediation jobs.
  2. Click Create Job Run from the Run Manager action menu.
  3. Complete the following fields in the Create Job Run window:
    FieldDescription
    Job*Select an existing mediation job from the drop-down menu.
    Job Run NameEnter a name for your mediation job run.
    Source PathEnter the source file path for the sFTP or S3 environment where the data file resides. For example, /product/mks/mediaton/usage-files. This field is pre-populated if you provided this information when you created the job.
    Source File NameEnter the source file name, for example, MD8-Usage-File.txt. This field is pre-populated with the information you provided when you created the job.
    Requires User Confirmation of Mediated Data Before Rating?Select one of the following options to determine whether or not a running job will pause and require approval before moving through the rating acceptance phase of the job run:
    • Always—Job run always pauses and requires approval even if there are no mediated errors.
    • Only When Errors are Present—Job run pauses and requires approval only when there are mediated errors.
    • Never—Job run does not pause or require approval. Data moves directly to rating approval. This is the default behavior.

    When a job is paused, you have the option to either approve or cancel the job.

    This setting overrides the original system job configuration, meaning that if the system job is set to Never and you select Always for this job run, the job will pause before moving to the rating acceptance step.

    *Indicates required field.

  4. Click Submit.

    Upon submission, the job runs in the system. The job displays in the job run list on the Run Manager page.

  5. If you configured the job to pause:
    • Review results in the Mediation Failed detail tab, especially failed or filtered records.
    • From the Run action menu on the Run Manager page, click either Approved or Cancel to approve or cancel the job run. If you approve it, successfully mediated records move on to the rating acceptance phase of the run.

Once your job runs, you can view the details of the run next for success or failure of mediation and rating acceptance.

Viewing Mediation Job Results

You can view the details of a job run for successes and failures.

  1. Select Mediation from the Gotransverse action menu . The Run Manager page displays a list of already run mediation jobs.
  2. Select a job from the list.

    The Job Run detail page displays Run Information and Status Summary sections, including general information about the job run such as the ID, Run Date, Job Run Name, and Run Status. Detail tabs like Import display information related to each phase of the job run.

    The detail tabs display the following:

    TabDescription
    ImportThe imported data from your raw usage data file.
    NormalizedThe usage data normalized, meaning the raw data was converted to a standardized table format so it can be processed during the mediation phase.
    Mediated SuccessThe normalized usage data that was successfully mediated, meaning the application performs business logic to convert the normalized data to a format that can be accepted by GTV’s rating system.

    Note: Mediation can take a single usage record in your file and convert it into more than one mediated record, if needed. For example, if there’s a usage record with multiple SRIDs, Mediation can convert the record into a mediated record for each SRID.

    Mediated FailedThe normalized usage data that failed to mediate. The display includes a Message column and a Details column with error message details for troubleshooting assistance. The Type column indicates whether a record failed due to an error or was filtered out based on a complex rule.
    Rating SuccessThe mediated usage data that was successfully accepted by GTV’s rating engine.
    Rating FailedThe mediated usage data that failed to be accepted by GTV’s rating engine. The display includes a Message column and a Details column with error message details for troubleshooting assistance.
    HistoryAction details surrounding each phase of the job run like Created and Mediation Process: Started.
  3. Review and troubleshoot data records, especially Mediated Failed and Rating Failed results, using the following tools:
    • Filter and sort are available for data records by detail tab. Click the column header you want to sort by.
    • Note: A detail tab must contain 100,000 or less records to use filter and sort. If there are more than 100,000 records, either the first 100,000 are displayed or a random sampling of the same size is displayed.

    • Click the information icon in the Details column of the record to view the record from the previous phase of the job run that is tied to the record you’re viewing.

If you require further assistance after troubleshooting efforts, contact Gotransverse support.

If the job run contains rating accepted records, the accepted usage data is now set to be consumed later during regular rating (converted into pricing) and billing (added to customers’ accounts and invoices) processes on the platform.

Creating a Filter

When you review or troubleshoot job run data records, there may be multitudes of records in the run. Filters allow you to search for specific records in a detail tab, for example, the Normalized detail tab.

For example, if you want to see only the records in the Mediated Success detail tab with a usage amount of 25, create a filter in the detail tab to filter by the Usage Amount column, with a Filter Condition of Equals, and a Value of 25.

  1. In a detail tab, click Add Filter.
  2. Complete the following fields:
    • Column*—Select the column you want to filter by. Drop-down menu selections vary based on data record types.
    • Filter Condition*—Select the filter condition for the column you selected. The options like Equals (=), Before (<) vary depending on which column you select.
    • Value*—Enter the value to combine with the filter condition like = 1.

      Note: * Indicates required field.

      You can select Create Another to create as many filters as you’d like to drill down deeper into the data.

  3. Click Create. The filters display above the detail tab’s data record list.
  4. Click the X on a displayed filter to clear it.

Editing a Mediation Job

You can modify mediation job settings, except for the job type.

  1. Select Mediation from the Gotransverse action menu .
  2. Click the Setup tab in the left pane. The Setup page displays a list of created mediation jobs.
  3. Click the ellipsis button under the Actions column next to the job you want to edit in the list, then select Edit.
  4. In the Edit System Job window, modify the desired fields. Fields that cannot be edited are grayed out like Type.
  5. Click Edit.

Deleting a Mediation Job

You can delete a job when it's no longer needed.

  1. Select Mediation from the Gotransverse action menu .
  2. Click Setup in the left pane. The Setup page displays a list of created mediation jobs.
  3. Click the ellipsis button under the Actions column next to the job you want to delete in the list, then select Delete.
  4. In the Confirmation window, click Yes to confirm the deletion.