ID968 - Insert Meter Readings from External Sources Overview & Sample:

Import meters from various DCAs into e-automate.

Jump to: Overview | Variables | Sample | Meter Type Mapping | Meter Validation Steps | Errors | Alert Functionality | OnDemand SSRS | Best Practices & Tips | Related Alerts

Click to subscribe

 

Overview

Overview

This process will push meters from various DCAs, as well as our other processes that import meters (i.e. KPAX, MPS Monitor), store them in a temp table and only import to e-automate the meters that fit the criteria for a valid meter. Only creating the meters that are needed in e-automate will help to reduce the bloat in the meter table.

When subscribing to ID968 you will also need to subscribe to the alert that corresponds to the DCA you wish to pull the meters from. If you are using multiple DCA's, you'll need to create a clone of ID968 for each DCA. See the integrations section to see the DCA's that ID968 works with. Notes on how to create a clone of the alert are here.

 

Run Schedule: Daily Early AM

Limited in the time and frequency that the alert can run, as either the process gets locked out and fails to complete because there’s so much competition for users in the meter tables, or worse, it locks out users and even remote tech connections by taking priority over those things.

Type of Output: Email/APP/On Demand Report

*  *  *

Variable

Variables

Variable 8: DCA Tool - Select which DCA Platform you are using from the drop-down list. One DCA tool per subscription. Details on cloning are here, and the available integrations are here.

Variable12: Meter Source - Indicate the e-automate Meter Source to be assigned to meters entered into your e-automate. More details on meter source can be found here.

Variable1:  Custom Property Control - The custom property is used to turn this integration OFF at either the Equipment or Customer Level. We build this Custom Property for you and default to ON, so this process is effectively ON for everything. See more details on using this custom property here.

THESE TWO VARIABLES SHOULD BE CLOSELY CONSIDERED AND REVIEWED:

VariableHidden2: Date Limiter - Do not import a new meter read unless it has been VariableHidden2 days since last Valid meter read. Set to -2 to completely suppress since-last-read functionality and use ONLY due-to-bill per VariableW. More details on this variable here.

VariableW: Billing Limiter - Import meter reads if no read in the last VariableW days AND the meter is inside a billing window (due to bill soon per the Billing Tolerance settings in e-automate). Set to -2 to suppress this functionality and use only days-since-last-read functionality in VariableHidden2 above. More details on this variable are here.

*  *  *

Sample

Sample

You will receive an email with a spreadsheet attachment for every subscription of ID968. Within the body of the email, you'll see:

1. The specific DCA tool that the meters are pulled from, which will correspond to the value in Variable 8 of your subscription.

2. Whether the process is in TEST or LIVE.

3. The total count of meters processed.

4. The number of meters that were pushed to e-automate.

The attached spreadsheet will have two tabs:

1. Action Items: This tab shows the meters that failed to be created in e-automate, the Message column of the spreadsheet will have the specific error for the meter. For details on the errors and how to resolve them, click here.

**If you see meters on this tab with a DCAReadingDate that is older than the current day of meters being pushed in, that indicates that the device has fallen off of monitoring.

2. No Action Needed: This tab shows all meters that were entered into e-automate.

*  *  *

APP

Meter Type Mapping

You will use the ID295 Model Mapping and Key Service app to map the meter types used in the DCA to the corresponding meter type in e-automate. If you are not subscribed to ID295, you can click here to subscribe to the app and here for the documentation on the app.

**DO NOT USE INTERNET EXPLORER AS YOUR BROWSER! IE is no longer supported, and our Apps do NOT work in the IE environment.

Jump to: Meter Types | Meter Mappings | Add Mapping

Go to your CEO Juice apps (if you don't know the URL, use http://localhost:8888)

1. From the home screen of the app, select model-mapping-and-key-services.

The two links in the top right of the screen that you will use are:

2. Meter Mappings - Used to map the meter types from the DCA to e-automate.

3. Metertypes - Shows the list of meter types from the DCA and whether the type is mapped or ignored.

Meter Types

Meter Types

The metertypes section of the app shows the DCA meter type names and which ones are mapped to a meter type in e-automate. You can use this section of the app to verify the DCA meter types available and ignore any ones that should be ignored.

There are three filters that can be used to limit the data in this section:

1. Source - Use the source drop down to select one DCA to see the available meter types.

2. MeterType Name - Enter the full or partial meter type name.

3. Show Ignored - Check this option to show meter types that have been set to ignored.

Once you have made your filter selections, click on the Search button to show the results.

4. Source - The name of the DCA the meter type is coming from.

5. MeterType - The meter type name from the DCA.

6. Mapped - Yes/No indicating if the meter type has been mapped to a meter type in e-automate.

7. Ignored - Option to check the box to ignore any meter types that are not currently mapped.

If you have any questions or need changes on what DCA Metertypes are being pushed in, please contact your DCA support team directly, as they can help you set which meters report.

Meter Mapping

Meter Mappings

The meter mapping section is where you will go to set the meter type from e-automate that will correspond to the meter type from the DCA.

1. The Add Mapping button will allow you to add a new mapping for a DCA meter type.

Two filters can be used to limit the data shown in the list:

2. Source - Use the source drop-down to show only meter mappings for a specific DCA.

3. EA Meter - Use the EA meter drop-down to show only meter mappings for a specific meter type from e-automate.

Click on the submit button to show the results of the filter.

4. EA Metertype - This is the name of the meter type from e-automate.

5. DCA Metertype - This is the name of the meter type from the DCA.

6. Fallback DCA Metertype - This is only needed when the same EA Metertype applies to more than one DCA Metertype. See more details on the Fallback meter type here.

7. Is Calculated - Yes/No used to indicate if the meter is calculated or not.

8. Source - The name of the DCA that the meter type is pulled from. 

9. The Pencil Icon will allow you to edit the mapping and make changes.

10. The trashcan icon will delete the mapping from the list.

Add Mapping

Add Mapping

To add a new mapping, click on the Add Mapping button.

1. EA Metertype: A drop-down list of the meter types available in your e-automate. Select the one that you want to map.

2. DCA Source: A drop-down of the available DCA sources. Select the DCA that you want to map to.

3. Is calculated: Yes/No option. If you select Yes on the mapping, you'll see a new option appear to set the calculation as either Summation or Difference. Select the option that applies.

4. DCA Metertype: A drop-down of the specific meter types available for the DCA selected in step two. Select the meter type that matches the meter type from e-automate in step one.

5. Fallback DCA metertype: Optional, t his is only needed when the same EA Metertype applies to more than one DCA Metertype. The list of options here will only show the meter types for the DCA selected in step two.

6. Click on the Create button to create the mapping.

Repeat the steps to Add Mapping until all meter types from the DCA are mapped.

* * *

Meter Validation Steps

Meter Validation Steps

The ID968 process goes through the following steps to determine if a meter reading should be created in e-automate. Any device not meeting the requirements below will not show on your daily report, but will still go to your processed folder. Any devices with errors entering meter reads will be noted on the daily email. Go here for more details on the possible errors. 

Jump To: Three Day Limitation | Equipment Record Match | Meter Required | Due for Billing | Meter Validation Buffer Check | Date Limiter Variable | Billing Limiter Variable

Three-day Limitation

1. Meter reading was received no more than three days ago. 

While in test mode, the process will consider meter readings from the past 45 days. Once the process is live, only reads from the past three days will be considered and will be shown on the daily emailed report. This function does not interact with the values set in either Variable W or Variable Hidden2, once the three days are up, the meter will not be included in the meters considered for billing.

This limitation is in place so that meters with errors that are 'unsolvable' drop off the report and don't keep reporting. 

Equipment Record Match

2. The equipment from the DCA is matched to an equipment record in e-automate.

The machines from the various DCAs are matched to equipment records in e-automate using the serial number. The serial number from the DCA must exactly match a serial number in e-automate.

There are a few exceptions to the exact match of the serial number, due to standard differences between the manufacturer and dealer:

Sharp: The last two zero's at the end of the serial number are removed when looking for a match.

Brother: The match is done based on the last nine digits of the serial number.

Beginning with the 20240523 version, for FM Audit, Printinista, HP SDS, and MPSM, we will match first on the DCA ID matching to the equipment ID in e-automate instead of the serial number. If there's no match at this level, the process will then look to the serial number. 

Matching based on the DCA ID should be available for KPAX in our next version (no ETA as of July 2024).

This will never be available for Sharp DCA as it is not part of the API.

**For any accommodation we've made by the manufacturer, the process looks first for an exact match on the serial number. If no match is found, then a second pass is done to match the serial numbers based on the exception for the manufacturer.

Meter Required

3. The meter is set as required on the equipment record.

On the equipment record in e-automate, the meter under consideration is marked as required:

Due for Billing

4. Per the contract record the equipment is associated with, the meter is due for billing or past due.

Whether a meter read is needed for billing is calculated based on the meter tolerances set in e-automate. The process will check for the difference between the trigger date of the alert and the Overage Next Billing Date on the contract. If this difference is less than the value in 'Before collection date', the meter is considered due to be billed. 

Example:

• Overage Next Billing date: 2/1/2024
• Before collection date: 14
• Date on meter read: 1/20/2024

The difference between the overage next billing date and the date of the meter read is 12. This value is less than the before collection date value of 14 and so the meter is considered 'due for billing'.

The Overage Next Billing date is the Billing on date on the Meter groups tab of the contract.

The billing meter tolerance values are set in Tools - Options - Contracts - Meters and overage options.

Meter Validation Buffer

5. The meter passes the meter validation buffer check.

The process uses the meter validation buffer percentage set in e-automate to determine if the meter read passes the buffer check. The meter validation buffer calculates the highest meter reading for the equipment that e-automate will allow without triggering a warning. 

The calculation: 

Maximum acceptable meter = Last Meter + (Number of days since last meter * Average Daily Usage * (1 + Meter Validation Buffer)

Example:

• Last meter: 901,006
• Number of days since last meter: 11 
• Average volume: 334 (Daily average is 11)
• Meter validation buffer: 25%

Maximum acceptable meter = 901,006 + (11 * 11 *(1 +.25)) = 901,157

To pass the validation buffer, the meter reading to be entered needs to be less than 901,157.

This percentage is set in Tools - Options - Equipment - Meters

Click here for the suggested best practice for setting the meter validation buffer.

Date Limiter

6. The date limiter variable is considered (Variable Hidden2).

The date limiter variable tells the process not to import a new meter read unless it has been Hidden2 days since the last valid meter read in e-automate. For the equipment under consideration, the process will check for the date of the last valid meter. If the difference between the meter date from the DCA and the last valid meter date in e-automate is greater than the value set in Hidden2, the meter will be created in e-automate.

You can set the Hidden2 variable to -2 to have the process not consider this variable and only check the value in Variable W.

Billing Limiter

7. Billing limiter variable considered (Variable W).

The billing limiter variable tells the process to import meter reads only if there is no read in the last VariableW days AND the meter is inside a billing window. This is a combination of step four where the process considers whether the meter is due to bill and then will further disallow meters if there is already a meter read entered within the days set in the variable.

You can set variable W to -2 to have the process not consider this variable and only check the value in the Hidden2 variable.

Once the process has gone through all of these steps, any meters that remain will be created in e-automate.

* * *

Errors

Errors

The action needed tab of the daily spreadsheet will list all meters with errors. The details on each error that may occur are listed below.

Jump to Specific Error Type: General | Invalid Meters | Meter Reset | HP\MPSM Specific

General

General Errors

• METERSOURCE DOES NOT EXIST!!: The meter source set in variable 12 is not valid and will need to be corrected before any meters can be pushed. More details on the meter source are here.
• Read Invalid due to other invalid reads in required set: Indicates there are required meters for this device that are invalid due to one of the reasons in the Meter is Invalid section. This may happen when the mono meter for a color machine is valid, but the color meter is not and both are required by the equipment record.

• Negative value indicates mapped meter not found: The meter type from the DCA has not been mapped to a meter type in e-automate. Click here for details on how to map the meter types.
• Duplicate Serials exist in EA: There is more than one equipment in e-automate with a serial number matching the serial number from the DCA. If needed, you can email help@ceojuice.com to request that ID968 only consider equipment records that are active. This may reduce the duplicate serial number errors.

Meter is Invalid

Meter is Invalid Errors

• Read Invalid due to less than previous: The meter from the DCA is less than the most recent previous meter in e-automate. Verify if the most recent meter in e-automate is accurate and invalidate it if needed to push the meter from the DCA.
• Read invalid due to no change: The meter from the DCA is the same as the most recent previous meter in e-automate. The meter read will drop off the report after three days. If you wish to have ID968 push meters when there has been no change, please email help@ceojuice.com to ask to have this new feature turned on for you.
• Read invalid due to overflow: The meter from the DCA has too many digits to be created in e-automate. 
• Read invalid due to other missing required reads: Indicates that a required meter is either not mapped or not being pushed from the DCA. Check that the meter type is mapped in the model mapping app and that a meter is available in the DCA.
• Read invalid due to Validation Buffer: The meter reading failed the buffer validation check. See notes here on how that is calculated. You can manually enter the meter into e-automate and click OK on the error warning. 
• Meter would post to a future date: The meter date provided from the DCA is a future date, and e-automate will not allow meters to be posted with a future date.
• Virtual Meter Formula is not valid: The formula to calculate the virtual meter is not valid.

Meter Reset

Meter Reset Errors

The two errors below often appear together and are both tied to equipment that has had a meter reset done.

• Actual update based on previous meter reset: There is a meter reset somewhere in the past, which means that e-automate will calculate a true 'Actual' to the best of its ability.
• Invalidated by Native Sanity Check: Parts of the sanity check within ID968 rely on the Actual meter, and it usually takes a long while after a reset before the historical data looks solid enough for the sanity check to give the meter a pass.

HP/MPSM Errors

HP/MPSM Errors

• MPSM Meterset Dates Error: This error indicates that the MPSM DCA is providing meter readings across multiple days, generally, this is the standard counter set on one date and the blended counter set on another, or vice-versa. E-automate can not handle this, there is only one date for the meter group. Check the devices in MPSM as well as the time zone that they are set for.
• MPSM Meterset Error: This is a bug in MPSM's API. They are currently working on a solution. The error is that we are not getting the Standard Counters from the API, only the Blended Counters. We see that these errors are higher on Monday's and many seem to self-resolve by the next day.

Below is the list of the Standard Counters we receive. If any of these meters are not coming through from MPSM, then you will receive this error. As of July 2024, MPSM has not been able to provide a solution for this "bug" in their API (please reach out to their support team support.americas@mpsmonitor.com directly with sample serial number, explaining that the standard counters are not coming through the API to CEO Juice). 

**FYI we only get Standard and Blended meters through the API. 

 

 

* * *

Alert Funcationality

Alert Functionality

This process takes the meters imported into the CEO Juice temp tables and only pushes meters into e-automate that meet the set criteria.

Jump to: Test vs. Live Mode | DCA Tools | EA Meter Source | EA Meter Type | EA Meter Tolerance | EA Meter Validation Buffer | Fallback Meter Type | New Features | Custom Property Control | Clones

Test vs. Live

Test vs. Live Mode

While in Test Mode, we will consider EVERY device regardless of your variable settings for Billing and Date Limiter (Variables Hidden2 and W). This is to provide you with as many devices for mapping meters as we can so that your mapping is as complete as possible. Test mode looks back 45 days in DCA for meters to report on.

Once the process is live, we will only report daily on meters that qualified for consideration based on your variable settings for Billing and Date Limiter (Variables Hidden2 and W).

DCA Tools

DCA Tools

Each DCA tool you want to use will require a separate ID968 subscription, with variable 8 set to one specific DCA tool. To use ID968 with additional tools, you'll create a cloned subscription to ID968 for each. For notes on creating a cloned subscription, click here. 

ID968 works with the following DCAs to import meters via the DCA API:

Available Now:

• ID29 FM Audit
• ID32 Sharp MICAS
• ID76 KPAX
• ID192 Printinista
• ID240 Kyocera
• ID311 HP SDS / MPS Monitor
• ID448 EKM

Currently in Beta Testing:

• ID365 NextGen
• ID763 Xerox
• ID848 3Manager

ID968 can also create meter readings in e-automate from an email inbox that is receiving emails that contain meter readings. This will require subscribing to ID398 to parse the email inbox to be used and push the meters to our background tables.

EA Meter Source

EA Meter Source

Each subscription of ID968 will require a meter source to be entered into variable 12. You can create a unique source for each subscription or use the same one.

Meter Sources are found in the Lists and Codes menu:

EA Meter Type

EA Meter Type

The list of meter types you have in e-automate is found in the Lists and Codes section:

The available meter sources in e-automate will be the ones available to be mapped to the DCA meter types. See here for the instructions on how to map the meter types between e-automate and the DCA.

EA Meter Tolerance

EA Meter Tolerance

The meter tolerance settings in e-automate determine what meters can be used for billing. The tolerances are set in Options, under the Tools menu:

1. Contracts

2. Meters/Overage Options

3. Billing meter tolerance

The two dates in the billing meter tolerance determine what meter readings are allowed for billing. If the billing date for the contract is 3/1/2025, based on the settings above, a meter reading could be used for billing if it was dated between 2/15/2025 and 3/15/2025.

EA Meter Validation Buffer

EA Meter Validation Buffer

The meter validation buffer is used to stop huge meters from being entered into e-automate by mistake. The meter validation buffer calculates the highest meter reading for the equipment that e-automate will allow without triggering a warning. 

The calculation: 

Maximum acceptable meter = Last Meter + (Number of days since last meter * Average Daily Usage * (1 + Meter Validation Buffer)

Example:

• Last meter: 901,006
• Number of days since last meter: 11 
• Average volume: 334 (Daily average is 11)
• Meter validation buffer: 25%

Maximum acceptable meter = 901,006 + (11 * 11 *(1 +.25)) = 901,157

To pass the validation buffer, the meter reading to be entered needs to be less than 901,157.

If you were manually entering a meter for this equipment that was higher than 901,157, you would receive an error:

This percentage is set in Tools - Options - Equipment - Meters

Click here for the suggested best practice on setting the meter validation buffer.

Fallback Meter Type

Fallback Meter Type

A fallback meter type is used when the main meter type that is mapped is not available.

An example of when a fallback meter is needed:

A B\W only device has a DCA meter type of Total Meter. A color device for that DCA has the options of Total B\W, Total Color, and Total Meter. In e-automate, you have the meter types Black Total and Color Total. 

If you map the DCA meter type of Total Meter to the e-automate meter type of Black Total, you will have color machines that are reporting the black and white meter as the total meter for the machine, which would be incorrect. Instead, you would want to map the DCA meter type of Total B\W to the e-automate meter type of Black Total and set the fallback meter type to be Total Meter. The color meter type would be set to Color Total with no fallback.

When pulling meters for the B\W only machines, the process will first check for the meter type of Total B\W and if that type doesn't exist, then would use the fallback meter type of Total Meter.

New Features

New Features

Several optional features have been added to the 2024.05.23 version of ID968. These features do not come standard with the integration and you will need to send an email to help@ceojuice.com to request the feature to be turned on. 

• Ignore inactive equipment in e-automate.
• Allow the same meter as the previous meter to be pushed into e-automate.
• For Billing and Date Limiters - Only consider the last valid meter created by ID968 instead of any/all previous valid meters.

Please note, if you have multiple ID968 subscriptions, these add-on features will apply to ALL of your subscriptions, not just one specific DCA type.

Custom Property Control

Custom Property Control

The custom property used to control whether an equipment record is considered for meter creation is set to default to ON, which means that ALL equipment records will be considered if a meter reading is found from the DCA. 

You can disable an equipment record from consideration by setting the custom property to OFF:

Meters for this specific piece of equipment will not be entered by ID968 now.

You can also turn the process OFF at the customer level:

When the custom property is set to OFF at the customer level, any equipment record with that customer as the main customer on the equipment record will NOT be considered for meter readings.

When the customer AY02 is set to OFF for ID968, no equipment records associated to that customer number will have meter reads entered.

Clones

Clones

Each DCA integration will need a separate subscription for ID968. After the first subscription is created, additional subscriptions are created by clicking on the + sign below ID968:

On the new subscription created, set the specific integration to be used in Variable 8. This clone of ID968 will not push sales orders into e-automate until moved to live mode by CEO Juice.

*  *  *

OnDemand SSRS Report

OnDemand SSRS Report

You also have an On Demand SSRS Report to review what has pushed in that day and what has had errors that day. This is essentially a duplicate to the daily email sent to those emails listed on your ID968 subscription.

 

Report shows on Page 1, any meters unable to push into eAuto due to error indicated:

 

Page 2 shows what meters have been pushed into eAuto:

*  *  *

Best Practices

Best Practices & Tips

Jump to: Meter Push Schedule | E-Agent Requests | Billing Limiter | Meter Validation Buffer | Meter not Pushing to EA | Custom Property

Meter Push Schedule

Meter Push Schedule

We highly recommend NOT pushing meters into e-automate every day. The main reason is table bloat in your meter tables in e-automate, which can cause performance issues for users working in e-automate. A secondary reason is the 'clutter' that daily meters can cause in the Meter Console. Users have a much harder time making sense of 1,000 rows of data compared to 50 - 60. If you absolutely, positively must push meters in daily, you'd set Variable Hidden2 to -1 and Variable W to -2.

E-Agent Requests

E-Agent Requests

Consider when your e-agent requests for meter readings send out against when you have your billing limiter variable set. To avoid sending out meter requests to customers expecting you to use the meter from the DCA, set the billing limiter to 1-2 days earlier than your e-agent task.

Also make sure the e-agent task runs later in the day than ID968, and not on weekends, since ID968 does not run on weekends.

Billing Limiter

Billing Limiter

A suggested best practice for Variable W is to set this to a value that is a little less than half your billing tolerance value; this is your best bet to have the most current read at the time of billing.

For example, if your billing tolerance is set to 7 days before and after the contract billing date, then we would recommend setting the Billing Limiter to 3. Assuming there's no other meter reads entered for the machine, you would get a meter entered at seven, four and one days prior to the contract billing date. You would also get a meter pushed two days after the contract billing date, if the contract has not been billed.

Meter Validation Buffer

Meter Validation Buffer

The suggested best practice for the meter validation buffer is to start at 50% and then increase to 80% if you are seeing too many warnings. The lower the percentage, the higher the number of warnings you'll receive, and we see that users start to ignore the warnings at that point.

Meter Not Pushing to EA

Meter Not Pushing to EA

What to look for when a meter is not pushing to e-automate:

1. Does the serial number in the DCA (or on the email) match the serial number in e-automate? See notes on the serial number matching here.
2. Is the device reporting on your Daily Summary 'Action Items' tab and showing an error?
3. Are the meters on the equipment record set as required? Screenshot of where that is set is here.
4. Are these previous meters in the meter reading console that are preventing the process from pushing meters based on the billing or date limiter? More details on the billing limiter are here and on the date limiter here.
5. Is the device offline in the DCA?

Custom Property

Custom Property

The custom property ZCJ_DCAMeterImport is used to turn this process OFF at either the equipment or customer level. CEO Juice will create this custom property as part of the install process and set the default value to ON, so the process is ON for everything. 

*  *  *

Related Alerts

Related Alerts

ID29 - FM Audit API Credentials

ID30 - Supplies Network API Credentials

ID32 - Sharp API Credentials

ID76 - KPAX API Credentials

ID192 - Printanista API Credentials

ID252 - Contract Equipment Missing Meter Collection Info

ID311 - MPS Monitor and/or HP SDS API  Credentials

ID398 - Emailed Meter Readings Mailbox Credentials

ID448 - EKM API Credentials