Customer Engagement API: Business Intelligence Data Overview

The Customer Engagement API provides Business Intelligence (BI) data related to networks, machines, active applications, sessions, and more. This article outlines the details of each attribute included in the input and output parameters, enabling users to effectively utilize the API for their business intelligence needs.

API Endpoint

Endpoint: 
GET /bpid/ver/bi/customer/engagement

API Input Parameters

The following are the inputs for the API. The apiKey is mandatory, while the others are optional. All inputs are of string type.

  • apiKey: User’s API key (mandatory).
  • companyNames: A comma-separated list of companies to include in the results (default: all companies).
  • divisionNames: A comma-separated list of divisions to include in the results (default: all divisions).
  • locationNames: A comma-separated list of locations to include in the results (default: all locations).
  • productLines: A comma-separated list of product lines to include in the results (default: all product lines).
  • dateRange: Options include:
    • last72hours (default)
    • last7days
    • last14days
    • last28days
    • last30days
    • thisquarter
    • lastquarter
    • thisyeartodate
    • custom
  • startTime: Beginning of the time range (required if dateRange=custom). Format: YYYY-MM-DD (UTC).
  • endTime: End of the time range (required if dateRange=custom). Format: YYYY-MM-DD (UTC).
  • format: Format of returned data (options: xml, json; default: xml).

API Output Parameters

The following displays the output for the API, which includes the count for the specified date range. The default date range is set to be the last 72 hours. The start time and end time are derived from the provided date range. For a custom date range, users must supply both the start and end time. All output values are positive integers.

  • MachineCountStart: This parameter indicates the total number of configured machines at the start time. A configured machine is defined as any piece of equipment that has been set up with all necessary configuration details. This count includes machines that have been registered and configured, regardless of their current connection status. Specifically, it encompasses actively connected machines, temporarily offline machines, newly configured machines awaiting their first connection, and previously connected machines that are pending reconnection.
  • MachineCountEnd: This parameter reflects the same count as MachineCountStart, but it is measured at the specified end time.
  • AppCountStart: This parameter represents the total number of active applications across all machines at the specified start time. It includes all types of applications.
  • AppCountEnd: This parameter reflects the same count as AppCountStart, but it is measured at the specified end time.
  • ServiceSessionCount: This parameter indicates the total number of distinct remote service connections established between the specified start and end times. Each count represents a unique remote support event and includes all successful connections, regardless of their duration.
  • ServiceSessionAvgMinutes: This metric represents the average duration of remote service connections during the time between the specified start and end times, calculated by dividing the total minutes of all sessions by the total number of sessions.
  • ServiceSessionTotalMinutes: This parameter represents the total aggregation of all remote service connection time in minutes during the period between the specified start and end times.
  • ServiceSessionHours: This parameter indicates the total whole hours of remote service connection time accumulated between the specified start and end times.
  • ServiceSessionMinutes: This parameter reflects the remaining minutes beyond the complete hours of remote service connection time during the period between the specified start and end times.
  • ServiceCasesCount: This metric monitors the automatically generated service notifications during the period between the specified start and end times. It includes the following features: identifying issues detected by ei3 applications, highlighting proactive maintenance opportunities, and indicating potential predictive maintenance events.
  • MachineOnlineCountStart: This parameter represents the number of online machines, defined as configured pieces of equipment that are actively connected. An online machine has established network connectivity and is capable of supporting ei3 applications, regardless of whether any applications are currently subscribed to.
  • MachineOnlineCountEnd: This parameter reflects the same count as MachineOnlineCountStart, but it is measured at a later point in time.
  • NetworkCountStart: This parameter represents the total number of configured networks, defined as sites where a Gateway has been set up with all necessary configuration details, regardless of their online or offline status. This includes fully operational sites, sites that are still in the setup phase, temporarily offline sites, sites pending activation, and sites that were previously online but are now offline.
  • NetworkCountEnd: This parameter reflects the same count as NetworkCountStart, but it is measured at a later point in time.
  • NetworkOnlineCountStart: This parameter represents the total number of online networks, defined as sites where the Gateway device is actively connected. This indicates that the site has achieved and is maintaining network connectivity, enabling potential communication with all machines at that location. This includes any site where the gateway is successfully communicating with ei3, regardless of the number of machines at the site, whether individual machines are online, or the level of data transmission occurring.
  • NetworkOnlineCountEnd: This parameter reflects the same count as NetworkOnlineCountStart, but it is measured at a later point in time.
  • MachinesNeverOnlineCountStart: This parameter tracks the number of configured machines that have never established a connection since their initial setup. This count is distinct from machines that were previously online but are currently offline, as it identifies equipment that has never achieved connectivity. This includes newly configured machines still pending their first connection, machines with potential configuration issues, machines facing installation challenges, and machines that may require technical intervention.
  • MachinesNeverOnlineCountEnd: This parameter reflects the same count as MachinesNeverOnlineCountStart, but it is measured at a later point in time.
  • MachinesNeverActiveCountStart: This parameter represents the count of configured machines that have never had any active applications.
  • MachinesNeverActiveCountEnd: This parameter reflects the same count as MachinesNeverActiveCountStart, but it is measured at a later point in time.
  • MachineOpportunityCountStart: This parameter defines a machine opportunity as an online machine that is successfully connected but does not currently have any applications activated.
  • MachineOpportunityCountEnd: This parameter reflects the same count as MachineOpportunityCountStart, but it is measured at a later point in time.
  • MachinesActiveAppsCountStart: This parameter represents the count of machines that have one or more active application subscriptions. Each machine can support up to eight different applications, and this metric counts any machine with at least one active subscription.
  • MachinesActiveAppsCountEnd: This parameter reflects the same count as MachinesActiveAppsCountStart, but it is measured at a later point in time.
  • ServiceCountStart: This parameter indicates the number of machines where the SERVICE or PREMIUM SERVICE application is active. This application enables secure remote access to machines, facilitating professional aftermarket support and maintenance capabilities.
  • ServiceCountEnd: This parameter reflects the same count as ServiceCountStart, but it is measured at a later point in time.
  • MonitorCountStart: This parameter shows the number of machines with active MONITOR subscriptions. This application provides basic machine monitoring capabilities.
  • MonitorCountEnd: This parameter reflects the same count as MonitorCountStart, but it is measured at a later point in time.
  • LifeCycleCountStart: This parameter tracks the number of machines with active LIFECYCLE subscriptions. This application focuses on equipment lifecycle management.
  • LifeCycleCountEnd: This parameter reflects the same count as LifeCycleCountStart, but it is measured at a later point in time.
  • ProductionCountStart: This parameter represents the count of machines with active PRODUCTION subscriptions. This application tracks manufacturing productivity metrics.
  • ProductionCountEnd: This parameter reflects the same count as ProductionCountStart, but it is measured at a later point in time.
  • DowntimeCountStart: This parameter shows the number of machines with active DOWNTIME subscriptions. This application analyzes and tracks machine availability and utilization.
  • DowntimeCountEnd: This parameter reflects the same count as DowntimeCountStart, but it is measured at a later point in time.
  • RecipeCountStart: This parameter tracks the number of machines with active RECIPE subscriptions. This application manages production recipes and settings.
  • RecipeCountEnd: This parameter reflects the same count as RecipeCountStart, but it is measured at a later point in time.
  • QualityCountStart: This parameter represents the count of machines with active QUALITY subscriptions. This application monitors and manages product quality parameters.
  • QualityCountEnd: This parameter reflects the same count as QualityCountStart, but it is measured at a later point in time.
  • SustainCountStart: This parameter shows the number of machines with active SUSTAIN subscriptions. This application focuses on sustainability and efficiency metrics.
  • SustainCountEnd: This parameter reflects the same count as SustainCountStart, but it is measured at a later point in time.
  • RoutingCountStart: This parameter indicates the number of machines with active ROUTING SERVICE subscriptions. This application enables IoT data routing to third-party destinations.
  • RoutingCountEnd: This parameter reflects the same count as RoutingCountStart, but it is measured at a later point in time.
  • AmphionsShippedCountStart: This parameter tracks the number of Amphions shipped to the company by ei3 up to the specified start date.
  • AmphionsShippedCountEnd: This parameter reflects the same count as AmphionsShippedCountStart, but it is measured at a later point in time.
  • MachinesOnlineInYearCountStart:This parameter indicates the number of machines that were actively connected in the past year but are not currently online. This signifies that the machines established network connectivity and were capable of supporting ei3 applications, regardless of whether any applications are currently subscribed.
  • MachinesOnlineInYearCountEnd: This parameter reflects the same count as MachinesOnlineInYearCountStart, but it is measured at a later point in time.
Print Friendly, PDF & Email