MachineMetrics

The MachineMetrics Developer Hub

Welcome to the MachineMetrics developer hub. You'll find comprehensive guides and documentation to help you start working with MachineMetrics as quickly as possible. Let's jump right in!

Suggest Edits

/reports/production

This endpoint returns selected data metrics rollups for a given time frame

 
posthttp://api.machinemetrics.com/reports/production

Body Params

start
date
required

Must be a valid ISO 8601 date-time format (e.g., "2017-07-19T10:00:00Z"); start must be before end

end
date
required

Must be a valid ISO 8601 date-time format (e.g., "2017-08-19T10:00:00Z"); end must be after start

data
array of objects
required

For a full list of valid metrics, see the data table below

groupBy
array of objects

Groups and aggregates data metrics by the specified grouping, in the order supplied. For a full list of valid groupings, see the groupBy table below

filter
object

Filters your query to include results for the items whose id is supplied in each respective array only. If the array is not supplied, or is empty, no filtering will be done on that item.

filter.machine
array of strings

Array of string machineIds

filter.machineGroup
array of strings

Array of string machineGroupIds

filter.jobOperation
array of strings

Array of string jobOperationIds

filter.shift
array of strings

Array of string shiftIds

filter.operator
array of strings

Array of string operatorIds

 

groupBy

Groups and aggregates the data metrics requested in the data array in the order provided. Grouping is always optional. If no groupBy is provided, data metrics get aggregated to the company level.

Example usage: groupBy: [ { "group": "machine" }, { "group": "day" }]

This will group and aggregate your selected data metrics by machine, and additionally for each machine, it will provide a rollup of each day for that metric.

item
notes

machine [String]

groups and aggregates selected data metrics by individual machine rollup (e.g. "citizen 1", "star 4" etc.)

machineGroup [String]

groups and aggregates selected data metrics by machine group rollup (e.g. "cell 1", "mazak" etc.)

jobOperation [String]

groups and aggregates selected data metrics by jobOperation rollup (e.g. "screw", "bolt" etc.)

jobOperationRun [String]

groups and aggregates selected data metrics by jobOperationRun rollup (e.g. a specific run of a jobOperation with a start and end date)

operator [String]

groups and aggregates selected data metrics by operator

hour [String]

groups and aggregates data metrics by hour (e.g. "1/1/2017 11:00 - 1/1/2017 12:00", ... "1/1/2017 12:00 - 1/1/2017 13:00". Hourly rollups have a maximum query range of one week. If more than a week is provided in the query range, only the most recent week will be returned

shift [String]

groups and aggregates selected data metrics by shift rollup (e.g. "first shift", "second shift" etc.)

day [String]

groups and aggregates selected data metrics by day (e.g., "8/1/17", "8/2/17"... "8/20/17")

week [String]

groups and aggregates selected data metrics by week (e.g., "7/31/17 - 7/7/17", ... "8/21/17 - 8/28/17")

month [String]

groups and aggregates selected data metrics by month (e.g. "1/1/2018 - 1/31/2018", ... "2/1/2018 - 2/28/2018")

quarter [String]

groups and aggregates selected data metrics by quarter (e.g. "1/1/2017 - 3/31/2017", ... "4/1/2017 - 6/30/2017")

data

The data metrics provided are aggregated up to each level of grouping. If no groupBy is provided, the requested data metrics will roll up to the company level.

Example usage: data: [ { "metric": "totalParts" }, { "metric": "timeInCut" }]

metric
description

totalParts [String]

Sum of all parts produced

rejectedParts [String]

Sum of parts rejected

timeInCycle [String]

Sum of time in cycle (ms)

timeSpindleRotating [String]

Sum of time when machine spindles were rotating (ms)

timeInCut [String]

Sum of time when machines were cutting (ms)

scheduledTotalParts [String]

Sum of all parts produced when machines were scheduled and not in setup

scheduledRejectedParts [String]

Sum of parts rejected when machines were scheduled and not in setup

scheduledTimeInCycle [String]

Sum of time in cycle when machines were scheduled and not in setup (ms)

productionTimeInCycle [String]

Sum of time in cycle when machines were in production (ms)

productionDowntime [String]

Sum of time when machines were in production but not in cycle (ms)

productionTime [String]

Sum of all time when machines were in production (ms)

setupTime [String]

Sum of all time when machines were in setup (ms)

scheduledTime [String]

Sum of all time when machines were scheduled and not in setup (ms)

unscheduledTime [String]

Sum of all time when machines were unscheduled (ms)

allTime [String]

Sum of all time (ms)

nonOptionalTime [String]

Sum of all time excluding optional shifts (ms)

expectedPartTime [String]

Maximum amount of time a given part is expected to take for any one jobOperation (ms)

idealPartTime [String]

Maximum amount of time a given part can ideally take for any one jobOperation (ms)

expectedSetupTime [String]

Sum of time expected to be spent in setup (ms)

downtime [String]

Sum of all machine downtime (ms)

plannedDowntime [String]

Sum of all machine downtime that was planned (ms)

unplannedDowntime [String]

Sum of all machine downtime that was unplanned (ms)

categorizedDowntime [String]

Sum of categorized machine downtime (ms)

uncategorizedDowntime [String]

Sum of uncategorized machine downtime (ms)

productionDowntime [String]

Sum of machine downtime that took place while machines were in production (ms)

goodParts [String]

Sum of all parts not rejected

rejectedParts [String]

Sum of all parts rejected

scrapRate [String]

1 - quality

scheduledIdealParts [String]

Sum of all parts that would have been produced for each machine operating at its best theoretical throughput for the entire length of scheduled time.

inCycleIdealParts [String]

Sum of all parts that would have been produced for each machine operating at its best theoretical throughput for the time it was in cycle.

partsGoal [String]

Weighted percent (as a value between 0 and 1) of parts created out of the set part goals.

partsGoalWarningThreshold [String]

Percent threshold (as value between 0 and 1) below which parts goal would be in warning state

partsGoalFailureThreshold [String]

Percent threshold ( as value between 0 and 1) below which parts goal would be in failure state

availability [String]

Rollup of availability across all included machines

performance [String]

Rollup of performance across all included machines

quality [String]

Rollup of quality across all included machines

oee [String]

Rollup of OEE across all included machines

oeeWarningThreshold [String]

Percent threshold (as value between 0 and 1) below which OEE would be in warning state

oeeFailureThreshold [String]

Percent threshold (as value between 0 and 1) below which OEE would be in failure state

ooe [String]

Rollup of OOE across all included machines

teep [String]

Rollup of TEEP across all included machines

utilizationRate [String]

Percent (as value between 0 and 1) of queried the queried time that machines have been in cycle

utilizationWarningThreshold [String]

Percent threshold (as value between 0 and 1) below which utilization would be in warning state

utilizationFailureThreshold [String]

Percent threshold (as value between 0 and 1) below which utilization would be in failure state

averagePartsPerHour [String]

Average number of parts created each hour over scheduled time

expectedPartsPerHour [String]

The expected number of parts that would be created each hour over scheduled time

idealPartsPerHour [String]

The most parts that could ideally be created each hour over scheduled time

minStartTime [String]

Earliest time that a job operation was active

maxEndTime [String]

Latest time that a job operation was active

Endpoint Example Usage

Below is an example of the /reports/production endpoint being queried for all parts produced and all time the machines were in cycle, broken down by day - and then further by machine - between July 19th, 2017 and July 21st, 2017. Additionally, this query is also filtered for three specific machines, and will only return totalParts and timeInCycle in the range for those machines.

The response returns the query range, the rollup at each grouping level, the items compose each grouping level, and a hash table of some additional information about the entities being grouped.

{
  "start":"2017-07-19T10:00:00Z",
  "end":"2017-07-21T10:00:00Z",
  "data": [
    {"metric":"totalParts"},
    {"metric":"timeInCycle"}
  ],
  "groupBy":[
    {"group":"day"},
    {"group":"machine"}
  ], 
  "filter": { 
    "machine": ["machine1Id", "machine2Id", "machine3Id"]
  }
}
{
  "range": {
    "start": "2017-07-19T10:00:00.000Z",
    "end": "2017-07-21T10:00:00.000Z"
  },
  "aggregate": {
    "totalParts": 8824,
    "timeInCycle": 291068400
  },
  "entities": {
    "day": {
      "0": {
        "start": "2017-07-19T10:00:00.000Z",
        "end": "2017-07-20T10:00:00.000Z",
        "shopDate": "2017-07-19T04:00:00.000Z"
      },
      "1": {
        "start": "2017-07-20T10:00:00.000Z",
        "end": "2017-07-21T10:00:00.000Z",
        "shopDate": "2017-07-20T04:00:00.000Z"
      }
    },
    "machine": {
      "machine1Id": {
        "id": "machine1Id",
        "name": "MACHINE 1"
      },
      "machine2Id": {
        "id": "machine2Id",
        "name": "MACHINE 2"
      },
      "machine3Id": {
        "id": "machine3Id",
        "name": "MACHINE 3"
      }
    }
  },
  "items": [
    {
      "entity": {
        "type": "day",
        "id": "0"
      },
      "aggregate": {
        "totalParts": 4295,
        "timeInCycle": 146361236
      },
      "items": [
        {
          "entity": {
            "type": "machine",
            "id": "machine3Id"
          },
          "aggregate": {
            "totalParts": 0,
            "timeInCycle": 9971
          }
        },
        {
          "entity": {
            "type": "machine",
            "id": "machine1Id"
          },
          "aggregate": {
            "totalParts": 3425,
            "timeInCycle": 80549950
          }
        },
        {
          "entity": {
            "type": "machine",
            "id": "machine2Id"
          },
          "aggregate": {
            "totalParts": 870,
            "timeInCycle": 65801315
          }
        }
      ]
    },
    {
      "entity": {
        "type": "day",
        "id": "1"
      },
      "aggregate": {
        "totalParts": 4529,
        "timeInCycle": 144707164
      },
      "items": [
        {
          "entity": {
            "type": "machine",
            "id": "machine3Id"
          },
          "aggregate": {
            "totalParts": 978,
            "timeInCycle": 19536320
          }
        },
        {
          "entity": {
            "type": "machine",
            "id": "machine1Id"
          },
          "aggregate": {
            "totalParts": 2741,
            "timeInCycle": 64656182
          }
        },
        {
          "entity": {
            "type": "machine",
            "id": "machine2Id"
          },
          "aggregate": {
            "totalParts": 810,
            "timeInCycle": 60514662
          }
        }
      ]
    }
  ]
}
Suggest Edits

/reports/downtime

This endpoint returns downtime (ms) rollups for a given time frame

 
posthttp://api.machinemetrics.com/reports/downtime

Body Params

start
date
required

Must be a valid ISO 8601 date-time format (e.g., "2017-07-19T10:00:00Z"); start must be before end

end
date
required

Must be a valid ISO 8601 date-time format (e.g., "2017-08-19T10:00:00Z"); end must be after start

groupBy
array of objects

Groups and aggregates downtimeMs by the specified grouping, in the order supplied. For a full list of valid groupings, see the groupBy table below

filter
object

Filters your query to include results for the items whose id is supplied in each respective array only. If the array is not supplied, or is empty, no filtering will be done on that item.

filter.machine
array of strings

Array of string machineIds

filter.machineGroup
array of strings

Array of string machineGroupIds

filter.jobOperation
array of strings

Array of string jobOperationIds

filter.shift
array of strings

Array of string shiftIds

filter.reason
array of strings

Array of string reasonIds

 

groupBy

Groups and aggregates the downtimeMs in the order provided. Grouping is always optional. If no groupBy is provided, downtimeMs gets aggregated to the company level.

Example: groupBy: [ { "group": "reason" }, { "group": "machine" }]

This will group and aggregate downtimeMs by downtime reason, and additionally for each machine, it will provide a rollup of each day for that metric.

item
notes

machine [String]

groups and aggregates downtimeMs by individual machine rollup (e.g. "citizen 1", "star 4" etc.)

machineGroup [String]

groups and aggregates downtimeMs by machine group rollup (e.g. "cell 1", "mazak" etc.)

jobOperation [String]

groups and aggregates downtimeMs by jobOperation rollup (e.g. "screw", "bolt" etc.)

shift [String]

groups and aggregates downtimeMs by shift rollup (e.g. "first shift", "second shift" etc.)

reason [String]

groups and aggregates downtimeMs by downtime reason (e.g., "Machine Maintenance", ... "Part Changeover"). Additionally, setup and uncategorized downtime is computed and provided when applicable

day [String]

groups and aggregates downtimeMs by day (e.g., "8/1/17", "8/2/17"... "8/20/17")

week [String]

groups and aggregates downtimeMs by week (e.g., "7/31/17 - 7/7/17", ... "8/21/17 - 8/28/17")

Endpoint Example Usage

Below is an example of the /reports/downtime endpoint being queried for all downtime (ms) broken down by downtime reason - and then further by machine for each reason - between July 19th, 2017 and August 19th, 2017. Additionally, this query is also filtered for three specific machines, and will only return downtime in that range for those machines.

The response returns the query range, the rollup at each grouping level, the items compose each grouping level, and a hash table of some additional information about the entities being grouped.

{
  "start":"2017-07-19T10:00:00Z",
  "end":"2017-08-19T10:00:00Z",
  "groupBy":[
    {"group":"reason"},
    {"group":"machine"}
  ], 
  "filter": { 
    "machine": ["machine1Id", "machine2Id", "machine3Id"]
  }
}
{
    "range": {
        "start": "2017-07-19T10:00:00.000Z",
        "end": "2017-08-19T10:00:00.000Z"
    },
    "aggregate": {
        "downtimeMs": 7644699,
        "recordCount": 8
    },
    "entities": {
        "reason": {
            "33": {
                "id": 33,
                "name": "Chipping Out",
                "color": "#dea638"
            },
            "95": {
                "id": 95,
                "name": "Part Changeover",
                "color": "#de7020"
            },
            "uncategorized": {
                "id": "uncategorized",
                "name": "Uncategorized",
                "color": "#444444",
                "virtual": true
            },
            "setup": {
                "id": "setup",
                "name": "Setup",
                "color": "#edde00",
                "virtual": true
            }
        },
        "machine": {
            "machine1Id": {
                "id": "machine1Id",
                "name": "MACHINE 1"
            },
            "machine2Id": {
                "id": "machine2Id",
                "name": "MACHINE 2"
            },
            "machine3Id": {
                "id": "machine3Id",
                "name": "MACHINE 3"
            }
        }
    },
    "items": [
        {
            "entity": {
                "type": "reason",
                "id": "33"
            },
            "aggregate": {
                "downtimeMs": 1731898,
                "recordCount": 4
            },
            "items": [
                {
                    "entity": {
                        "type": "machine",
                        "id": "machine1Id"
                    },
                    "aggregate": {
                        "downtimeMs": 544259,
                        "recordCount": 2
                    }
                },
                {
                    "entity": {
                        "type": "machine",
                        "id": "machine2Id"
                    },
                    "aggregate": {
                        "downtimeMs": 837607,
                        "recordCount": 1
                    }
                },
                {
                    "entity": {
                        "type": "machine",
                        "id": "machine3Id"
                    },
                    "aggregate": {
                        "downtimeMs": 350032,
                        "recordCount": 1
                    }
                }
            ]
        },
        {
            "entity": {
                "type": "reason",
                "id": "95"
            },
            "aggregate": {
                "downtimeMs": 5912801,
                "recordCount": 4
            },
            "items": [
                {
                    "entity": {
                        "type": "machine",
                        "id": "machine3Id"
                    },
                    "aggregate": {
                        "downtimeMs": 5912801,
                        "recordCount": 4
                    }
                }
            ]
        }
    ]
}
Suggest Edits

/reports/quality

This endpoint returns rejectCount rollups for a given time frame

 
posthttp://api.machinemetrics.com/reports/quality

Body Params

start
date
required

Must be a valid ISO 8601 date-time format (e.g., "2017-07-19T10:00:00Z"); start must be before end

end
date
required

Must be a valid ISO 8601 date-time format (e.g., "2017-08-19T10:00:00Z"); end must be after start

groupBy
array of objects

Groups and aggregates rejectCount by the specified grouping, in the order supplied. For a full list of valid groupings, see the groupBy table below

filter
object

Filters your query to include results for the items whose id is supplied in each respective array only. If the array is not supplied, or is empty, no filtering will be done on that item.

filter.machine
array of strings

Array of string machineIds

filter.machineGroup
array of strings

Array of string machineGroupIds

filter.jobOperation
array of strings

Array of string jobOperationIds

filter.shift
array of strings

Array of string shiftIds

filter.reason
array of strings

Array of string reasonIds

 

groupBy

Groups and aggregates the rejectCount in the order provided. Grouping is always optional. If no groupBy is provided, rejectCount gets aggregated to the company level.

Example: groupBy: [ { "group": "reason" }, { "group": "machine" }]

This will group and aggregate rejectCount by reject reason, and additionally for each machine, it will provide a rollup of each day for that metric.

item
notes

machine [String]

groups and aggregates rejectCount by individual machine rollup (e.g. "citizen 1", "star 4" etc.)

machineGroup [String]

groups and aggregates rejectCount by machine group rollup (e.g. "cell 1", "mazak" etc.)

jobOperation [String]

groups and aggregates rejectCount by jobOperation rollup (e.g. "screw", "bolt" etc.)

shift [String]

groups and aggregates rejectCount by shift rollup (e.g. "first shift", "second shift" etc.)

reason [String]

groups and aggregates rejectCount by reject reason (e.g., "Bad Part", ... "Broken Tool")

day [String]

groups and aggregates rejectCount by day (e.g., "8/1/17", "8/2/17"... "8/20/17")

week [String]

groups and aggregates rejectCount by week (e.g., "7/31/17 - 7/7/17", ... "8/21/17 - 8/28/17")

Endpoint Example Usage

Below is an example of the /reports/quality endpoint being queried for all rejects broken down by reject reason - and then further by machine for each reason - between July 19th, 2017 and August 19th, 2017. Additionally, this query is also filtered for three specific machines, and will only return rejects in that range for those machines.

The response returns the query range, the rollup at each grouping level, the items compose each grouping level, and a hash table of some additional information about the entities being grouped.

{
  "start":"2017-07-19T10:00:00Z",
  "end":"2017-08-19T10:00:00Z",
  "groupBy":[
    {"group":"reason"},
    {"group":"machine"}
  ], 
  "filter": { 
    "machine": ["machine1Id", "machine2Id", "machine3Id"]
  }
}
{
  "range": {
    "start": "2017-07-19T10:00:00.000Z",
    "end": "2017-08-19T10:00:00.000Z"
  },
  "aggregate": {
    "rejectCount": 150,
    "recordCount": 75
  },
  "entities": {
    "reason": {
      "24": {
        "id": 24,
        "name": "Chip Impressions",
        "color": "#5f5da8"
      },
      "37": {
        "id": 37,
        "name": "Burrs",
        "color": "#14f2e5"
      }
    },
    "machine": {
      "machine1Id": {
        "id": "machine1Id",
        "name": "MACHINE 1"
      },
      "machine2Id": {
        "id": "machine2Id",
        "name": "MACHINE 2"
      },
      "machine3Id": {
        "id": "machine3Id",
        "name": "MACHINE 3"
      }
    }
  }
  "items": [
    {
      "entity": {
        "type": "reason",
        "id": "24"
      },
      "aggregate": {
        "rejectCount": 25,
        "recordCount": 10
      },
      "items": [
        {
          "entity": {
            "type": "machine",
            "id": "machine1Id"
          },
          "aggregate": {
            "rejectCount": 15,
            "recordCount": 5
          }
        },
        {
          "entity": {
            "type": "machine",
            "id": "machine2Id"
          },
          "aggregate": {
            "rejectCount": 10,
            "recordCount": 5
          }
        }
      ]
    },
    {
      "entity": {
        "type": "reason",
        "id": "37"
      },
      "aggregate": {
        "rejectCount": 125,
        "recordCount": 65
      },
      "items": [
        {
          "entity": {
            "type": "machine",
            "id": "machine2Id"
          },
          "aggregate": {
            "rejectCount": 79,
            "recordCount": 53
          }
        },
        {
          "entity": {
            "type": "machine",
            "id": "machine3Id"
          },
          "aggregate": {
            "rejectCount": 46,
            "recordCount": 12
          }
        }
      ]
    }
  ]
}
Suggest Edits

/reports/alarm

This endpoint returns selected alarm-related data metrics rollups for a given time frame

 
posthttp://api.machinemetrics.com/reports/alarm

Body Params

start
date
required

Must be a valid ISO 8601 date-time format (e.g., "2017-07-19T10:00:00Z"); start must be before end

end
date
required

Must be a valid ISO 8601 date-time format (e.g., "2017-08-19T10:00:00Z"); end must be after start

data
array
required

For a full list of valid metrics, see the data table below

groupBy
array

Groups and aggregates data metrics by the specified grouping, in the order supplied. For a full list of valid groupings, see the groupBy table below

filter
object

Filters your query to include results for the items whose id is supplied in each respective array only. If the array is not supplied, or is empty, no filtering will be done on that item.

filter.machine
array of strings

Array of string machineIds

filter.machineGroup
array of strings

Array of string machineGroupIds

filter.state
array of strings

Array of string states. Valid states are WARNING and FAULT

filter.nativeCode
array of strings

Array of string nativeCodes

filter.nativeCodeId
array of strings

Array of string nativeCodeIds

reject
object

Filters your query to reject results for the items whose id is supplied in each respective array only. If the array is not supplied, or is empty, no filtering will be done on that item. When rejecting machineGroups, all the associated machines are removed from the results. Additionally, rejected values take precedence over filtered values

reject.machine
array of strings

Array of string machineIds

reject.machineGroup
array of strings

Array of string machineGroupIds

reject.state
array of strings

Array of string states. Valid states are WARNING and FAULT

reject.nativeCode
array of strings

Array of string nativeCodes

reject.nativeCodeId
array of strings

Array of string nativeCodeIds

 

groupBy

Groups and aggregates the data metrics requested in the data array in the order provided. Grouping is always optional. If no groupBy is provided, data metrics get aggregated to the company level.

Example usage: groupBy: [ { "group": "machine" }, { "group": "day" }]

This will group and aggregate your selected data metrics by machine, and additionally for each machine, it will provide a rollup of each day for that metric.

item
notes

machine [String]

groups and aggregates selected data metrics by individual machine rollup (e.g. "citizen 1", "star 4" etc.)

machineGroup [String]

groups and aggregates selected data metrics by machine group rollup (e.g. "cell 1", "mazak" etc.)

nativeCode [String]

groups and aggregates selected data metrics by nativeCode

state [String]

groups and aggregates selected data metrics by state (e.g., "FAULT" or "WARNING")

hour [String]

groups and aggregates selected data metrics by hour (e.g., "2018-01-25T10:00:00.000Z - "2018-01-25T11:00:00.000Z""). Hourly rollups have a maximum query range of one week. If more than a week is provided in the query range, only the most recent week will be returned

day [String]

groups and aggregates selected data metrics by day (e.g., "8/1/17", "8/2/17"... "8/20/17")

week [String]

groups and aggregates selected data metrics by week (e.g., "7/31/17 - 7/7/17", ... "8/21/17 - 8/28/17")

data

The data metrics provided are aggregated up to each level of grouping. If no groupBy is provided, the requested data metrics will roll up to the company level.

Example usage: data: [ { "metric": "durationMs" }, { "metric": "recordCount" }]

metric
notes

durationMs [String]

Sum of total duration in milliseconds

minStartTime [String]

Earliest time that an alarm state was active

maxEndTime [String]

Latest time that an alarm state was active

recordCount [String]

Sum of total number of alarms

machineCount [String]

Number of distinct machines that were in alarm state

Endpoint Example Usage

Below is an example of the /reports/alarm endpoint being queried for time in alarm state, the earliest and latest time in the alarm state, and the total number of alarms broken down by nativeCode between July 19th, 2017 and July 21st, 2017. Additionally, this query is also filtered for three specific machines.

The response returns the query range, the rollup at each grouping level, the items compose each grouping level, and a hash table of some additional information about the entities being grouped.

{
  "start":"2017-07-19T10:00:00Z",
  "end":"2017-07-21T10:00:00Z",
  "data": [
    {"metric":"durationMs"},
    {"metric":"minStartTime"},
    {"metric":"maxEndTime"},
    {"metric":"recordCount"},
    {"metric":"machineCount"}
  ],
  "groupBy":[
    {"group":"nativeCode"}
  ], 
  "filter": { 
    "machine": ["machine1Id", "machine2Id", "machine3Id"]
  }
}
{
    "range": {
        "start": "2017-07-19T10:00:00.000Z",
        "end": "2017-07-21T10:00:00.000Z"
    },
    "aggregate": {
        "durationMs": 1874382105,
        "minStartTime": "2017-07-19T04:00:00.000Z",
        "maxEndTime": "2017-07-21T10:00:00.000Z",
        "recordCount": 1130,
      	"machineCount": 3
    },
    "entities": {
        "nativeCode": {
            "34": {
                "id": 34,
              	"nativeCode": "nativeCode1",
                "message": "Emergency stop",
                "state": "WARNING"
            },
            "98": {
              	"id": 98,
                "nativeCode": "nativeCode2",
                "message": "Remote I/O failure",
                "state": "FAULT"
            }
        }
    },
    "items": [
        {
            "entity": {
                "type": "nativeCode",
                "id": "34"
            },
            "aggregate": {
                "durationMs": 291723232,
                "minStartTime": "2017-07-19T04:00:00.000Z",
                "maxEndTime": "2017-07-21T10:00:00.000Z",
                "recordCount": 53,
              	"machineCount": 1
            }
        },
        {
            "entity": {
                "type": "nativeCode",
                "id": "98"
            },
            "aggregate": {
                "durationMs": 1582658873,
                "minStartTime": "2017-07-19T11:18:25.378Z",
                "maxEndTime": "2017-07-21T09:36:09.678Z",
                "recordCount": 1077,
              	"machineCount": 3
            }
        }
    ]
}
Suggest Edits

/reports/alarm/instances

This endpoint returns a specified number of individual alarms instances

 
posthttp://api.machinemetrics.com/reports/alarm/instances

Body Params

start
date
required

Must be a valid ISO 8601 date-time format (e.g., "2017-07-19T10:00:00Z"); cannot be provided if using startId. Either start or startId is required

startId
int32
required

Specific alarmId to use as a starting point. Cannot be provided if using start. Either startId or start is required

limit
int32

Number of instances to return; must be less than or equal to 200. Default value is 200

direction
string

Direction in which alarms are returned. Must be either ASC or DESC. Default value is ASC

filter
object

Filters your query to include results for the items whose id is supplied in each respective array only. If the array is not supplied, or is empty, no filtering will be done on that item

filter.machine
array of strings

Array of string machineIds

filter.machineGroup
array of strings

Array of string machineGroupIds

filter.state
array of strings

Array of string states. Valid states are WARNING and FAULT

filter.nativeCode
array of strings

Array of string nativeCodes

filter.nativeCodeId
array of strings

Array of string nativeCodeIds

reject
object

Filters your query to reject results for the items whose id is supplied in each respective array only. If the array is not supplied, or is empty, no filtering will be done on that item. When rejecting machineGroups, all the associated machines are removed from the results. Additionally, rejected values take precedence over filtered values

reject.machine
array of strings

Array of string machineIds

reject.machineGroup
array of strings

Array of string machineGroupIds

reject.state
array of strings

Array of string states. Valid states are WARNING and FAULT

reject.nativeCode
array of strings

Array of string nativeCodes

reject.nativeCodeId
array of strings

Array of string nativeCodeIds

 

Endpoint Example Usage

Below is an example of the reports/alarm/instances endpoint being queried for 5 alarms that occur starting "2018-01-01T10:00:00Z".

{
	"start": "2018-01-01T10:00:00Z",
	"limit": 5,
	"direction": "ASC"
}
{
    "entities": {
        "machine": {
            "machine1Id": {
                "id": "machine1Id",
                "name": "machine 1"
            },
            "machine2Id": {
                "id": "machine2Id",
                "name": "machine 2"
            }
        }
    },
    "range": {
        "start": "2018-01-01T10:00:00.000Z",
        "limit": 5,
        "direction": "ASC",
        "startId": null
    },
    "instances": [
        {
            "alarmId": 73899390,
            "durationMs": 16252105,
            "state": "WARNING",
            "machineId": "machine1Id",
            "nativeCode": "nativeCode 1",
            "message": "Auto operation pause signal ON (nativeCode 1)",
            "start": "2018-01-02T03:38:54.875Z",
            "end": "2018-01-02T08:09:46.980Z"
        },
        {
            "alarmId": 73899392,
            "durationMs": 16252105,
            "state": "WARNING",
            "machineId": "machine1Id",
            "nativeCode": "nativeCode 2",
            "message": "Auto operation pause signal ON (nativeCode 2)",
            "start": "2018-01-02T03:38:54.876Z",
            "end": "2018-01-02T08:09:46.981Z"
        },
        {
            "alarmId": 73936076,
            "durationMs": 7961734,
            "state": "WARNING",
            "machineId": "machine1Id",
            "nativeCode": "nativeCode 1",
            "message": "Auto operation pause signal ON (nativeCode 1)",
            "start": "2018-01-02T08:10:12.715Z",
            "end": "2018-01-02T10:22:54.449Z"
        },
        {
            "alarmId": 73936077,
            "durationMs": 7961735,
            "state": "WARNING",
            "machineId": "machine1Id",
            "nativeCode": "nativeCode2",
            "message": "Auto operation pause signal ON (nativeCode 2)",
            "start": "2018-01-02T08:10:12.715Z",
            "end": "2018-01-02T10:22:54.450Z"
        },
        {
            "alarmId": 73954579,
            "durationMs": 1848511,
            "state": "WARNING",
            "machineId": "machine2Id",
            "nativeCode": "nativeCode 3",
            "message": "Overload 1 (nativeCode 3)",
            "start": "2018-01-02T10:11:16.176Z",
            "end": "2018-01-02T10:42:04.687Z"
        }
    ]
}

If you know the specific alarmId you'd like to use as a starting point for your query - as opposed to using a start time - you may use startId in the request in lieu of start. As there can possibly be many alarms that went into effect at the exact same time, using a startId will ensure alarms will be returned in a consistent sequential order, which may be useful for pagination, lazy loading etc. of alarms.

Below is an example of 5 alarms that occur before alarm 73899392.

{
	"startId": 73899392,
	"limit": 5,
	"direction": "DESC"
}
{
    "entities": {
        "machine": {
            "machine1Id": {
                "id": "machine1Id",
                "name": "machine 1"
            },
            "machine3Id": {
                "id": "machine3Id",
                "name": "machine 3"
            }
        }
    },
    "range": {
        "start": null,
        "limit": 5,
        "direction": "DESC",
        "startId": 73899392
    },
    "instances": [
        {
            "alarmId": 73899390,
            "durationMs": 16252105,
            "state": "WARNING",
            "machineId": "machine1Id",
            "nativeCode": "nativeCode 1",
            "message": "Auto operation pause signal ON (nativeCode 1)",
            "start": "2018-01-02T03:38:54.875Z",
            "end": "2018-01-02T08:09:46.980Z"
        },
        {
            "alarmId": 73886370,
            "durationMs": 98351786,
            "state": "WARNING",
            "machineId": "machine1Id",
            "nativeCode": "nativeCode 2",
            "message": "Auto operation pause signal ON (nativeCode 2)",
            "start": "2018-01-01T00:19:17.321Z",
            "end": "2018-01-02T03:38:29.107Z"
        },
        {
            "alarmId": 73886369,
            "durationMs": 98351785,
            "state": "WARNING",
            "machineId": "machine1Id",
            "nativeCode": "nativeCode 1",
            "message": "Auto operation pause signal ON (nativeCode 1)",
            "start": "2018-01-01T00:19:17.321Z",
            "end": "2018-01-02T03:38:29.106Z"
        },
        {
            "alarmId": 73881113,
            "durationMs": 27617344,
            "state": "WARNING",
            "machineId": "machine1Id",
            "nativeCode": "nativeCode 2",
            "message": "Auto operation pause signal ON (nativeCode 2)",
            "start": "2017-12-31T16:38:34.489Z",
            "end": "2018-01-01T00:18:51.833Z"
        },
        {
            "alarmId": 73865316,
            "durationMs": 239554986,
            "state": "WARNING",
            "machineId": "machine3Id",
            "nativeCode": "nativeCode 10",
            "message": "Remote I/O failure (nativeCode 10)",
            "start": "2017-12-30T17:14:08.148Z",
            "end": "2018-01-02T11:46:43.134Z"
        }
    ]
}
Suggest Edits

/erp/jobdispatch/start

Starts a new job run on a machine.

 
posthttp://api.machinemetrics.com/erp/jobdispatch/start

Body Params

erpJobOperationRunId
string
required

Unique ID used by the ERP to identify this Job Run.

erpMachineId
string
required

Unique ID used by the ERP to represent the machine for this Job Run.

jobName
string
required

The name of the associated Job in MachineMetrics.

operationName
string

The name of the associated operation in MachineMetrics.

lotName
string

The name of the associated lot in MachineMetrics.

partName
string

The name of the associated part in MachineMetrics.

startInSetup
boolean

If true the Job Run will be started in Setup. Otherwise it will be started in Production.

startAt
string

The start date and time of the Job Run in UTC. If not provided, the job run will start at the time of the request. Must be a valid ISO 8601 date-time format (e.g., "2017-07-19T10:00:00Z").

dueAt
string

The due date for the specified job in UTC. Only used when creating a new job.

jobOperationDescription
string

A description of the job. Only used when creating a new job.

partValue
double

The value of the part being produced by a job. Only used when creating a new job. Can be a decimal value. Example: 1.25

quantityRequired
int32

The quantity of parts required for the job. Only used when creating a new job.

expectedSetupTime
int32

The amount of time this job run should be expected to be in setup in seconds. When creating a new job this will be saved as the default value.

idealPartTime
int32

The ideal amount of time in milliseconds it takes for one part to be produced. When creating a new job this will be saved as the default value.

expectedPartTime
int32

The amount of time it is expected for a part to be produced. When creating a new job this will be saved as the default value.

 

Endpoint Example Usage

Below is an example of the /erp/jobdispatch/start endpoint being used to start a job called 1001. When dispatching a job, MachineMetrics will first attempt to find an existing job using the jobName, lotName, operationName, and partName parameters from the request body. If no corresponding job exists, it will be created using the body parameters that are denoted above as Only used when creating a new job.

{
  "erpJobOperationRunId": "01", 
  "erpMachineId": "2",
  "startInSetup": false,
  "startAt": "2017-10-10T10:11:00.000Z",
  "dueAt": "",
  "jobName": "Spacely Sprockets",
  "jobOperationDescription": "Sprockets for Spacely Space Sprockets, Inc.",
  "lotName": null,
  "partName": "Sprocket001",
  "partValue": 1.23,
  "quantityRequired": 1000,
  "expectedSetupTime": 600,
  "expectedPartTime": 120000,
  "idealPartTime": 100000
}
Suggest Edits

/erp/jobdispatch/:id

This endpoint returns data from the specified job run.

 
gethttp://api.machinemetrics.com/erp/jobdispatch/id

Path Params

id
string
required

The specified Job Run ERP ID

 

Endpoint Example Usage

Below is an example response from the /erp/jobdispatch/:id endpoint.

The response returns the start and end dates for the job run as well as metrics including the total number of parts that were produced during the run, number of good parts, number of scrap parts, and number of nonconforming parts.

{
    "startAt": "2017-03-09T18:20:18.000Z",
    "endAt": null,
    "metrics": {
        "totalParts": 2069,
        "goodParts": 2069,
        "scrapParts": 0,
        "nonconformParts": 0
    }
}

Response Data

Item
Notes

startAt :[String]

The date and time that the job run started formatted as an ISO string.

endAt: [String]

The date and time that the job run ended formatted as an ISO string. Can be null if job run is still in progress.

metrics: [Object]

An object containing metrics about the job run.

metrics.totalParts: [Integer]

Integer signifying the total number of parts produced by this job run including good parts, scrap parts, and nonconforming parts.

metrics.goodParts: [Integer]

Integer signifying the number of good (not rejected) parts produced during this job run.

metrics.scrapParts: [Integer]

Integer signifying the number of scrap parts produced during this job run.

metrics.nonconformParts: [Integer]

Integer signifying the number of nonconforming parts produced during this job run.

Suggest Edits

/erp/jobdispatch/stop

Stops the specified Job Run

 
posthttp://api.machinemetrics.com/erp/jobdispatch/stop

Body Params

erpJobOperationRunId
string
required

The unique id of the job run to be stopped.

endAt
date-time

The UTC time the specified job run ended. If no value is provided the default value is the time the request is received.

 

Endpoint Example Usage

Below is an example of the /erp/jobdispatch/stop endpoint being used to stop a Job Run with an ERP ID of 01 at 12:00 on January 4th, 2018.

{
  "erpJobOperationRunId": "01",
  "endAt": "2018-01-04T12:00:00.000Z"
}
Suggest Edits

/jobs/import

Imports a list of jobs from file.

 
posthttp://api.machinemetrics.com/jobs/import?type=fileFormat

Query Params

fileFormat
string

The format of the jobs file being used.

Body Params

csvFile
file
required

The CSV file being imported.

autoArchive
boolean

Set this to true if you want to archive all jobs that are not included in the CSV File

 

fileFormat

The format of the jobs file being imported. Acceptable values are 'mm', 'inforVisual', and 'inforLN'. If no value is provided, job import will be assumed to be in the MachineMetrics format. You can find more information about that format as well as a temple here: https://support.machinemetrics.com/hc/en-us/articles/222971927-Job-Import-CSV-Format.

We also support two other formats

Format String
Description

mm (default)

The default format. A CSV file formatted as specified here: https://support.machinemetrics.com/hc/en-us/articles/222971927-Job-Import-CSV-Format

inforVisual

A jobs CSV exported from Infor VISUAL.

inforLN

A jobs XLSX file exported from Infor LN.

Suggest Edits

Getting Started with Web Sockets

Use websockets for real-time data. This document outlines how to connect and details each socket channel available.

 

The MachineMetrics real-time web socket APIs are built on top of socket.io.

Core Events and Commands

All channels support the following core events and commands. Each channel provides additional events and commands that are specific to their use case.

Event
Description

connect

Fired when the socket connection is established.

disconnect

Fired when the socket connection is lost.

channel_error

Fired when a general error occurs within the channel infrastructure. Sends the error message in the payload.

channel_join_success

Fired when a channel is successfully joined.

channel_join_failure

Fired when an attempt to join a channel fails. Sends the error message in the payload.

Command
Description

join

Invoked to join a channel. Must provide a JSON object containing an access token and any additional parameters required by the channel.

leave

Invoked to leave a channel.

Joining a Channel

Channels can be thought of as endpoints. Each channel provides distinct information from one another and provide their own protocol beyond the core join and leave messages available on all channels.

Authentication to a socket is done when a channel is joined. To authenticate with a socket, an access token must be provided. Access tokens can be retrieved via OAuth, or they can be generated as non-expiring API keys in the MachineMetrics application. API Keys should never be used in a web application or other setting where the key may be discovered by the user.

const socket = io('https://api.machinemetrics.com/CHANNEL_PATH');

socket.on('connect', () => {
  socket.emit('join', {
    token: 'access-token',
  });
});

socket.on('channel_error', ({ code, message }) => {
  console.error('channel_error', code, message);
});

socket.on('channel_join_failure', ({ code, message }) => {
  console.error('channel_join_failure', code, message);
});

socket.on('channel_join_success', () => {
  console.log('channel_join_success');
});

socket.open();
Suggest Edits

/events/machine/diagnostics

For client applications that require real-time information on changes to raw data coming off of manufacturing equipment, the diagnostics channel should be used.

 

In addition to the core events and commands available on all sockets, the Diagnostics socket adds the following:

Event
Description

update

Fires when the value for a particular data item has changed.

channel_error_diagnostics

Fires when an error occurs specific to the diagnostics channel.

Command
Description

set_machines

Invoked after the channel is joined to provide the set of machines that will be reported on. set_machines can be called multiple times to update the set of machines. Must provide a JSON array of machine IDs.

join

In addition to providing the access token, you must also provide a stream to retrieve the data from. Currently, the only supported value for this is "raw".

Once set_machines is called, update is called once for every metric on every machine that is being managed by the channel. After the current value for each of those metrics have been reported, the update event will only be fired when changes to those values occur.

const socket = io('https://api.machinemetrics.com/events/machine/diagnostics');

socket.on('connect', () => {
  socket.emit('join', {
    token: 'access-token',
    stream: 'raw',
  });
});

socket.on('channel_error', (e) => {
  console.error('channel_error', e);
});

socket.on('channel_join_success', () => {
  console.log('channel_join_success');
  socket.emit('set_machines', [
    'MACHINE_ID1',
    'MACHINE_ID2',
    'MACHINE_ID3',
  ]);
});

socket.on('update', (data) => {
  console.log(data);
});

socket.on('channel_join_failure', (e) => {
  console.error('channel_join_failure', e);
});

socket.open();

Data Structure for update Event Payload

{
  machineId: 'MACHINE_ID1',
  timestamp: '2018-01-03 20:43:08.132+00:00',
  key: 'PZload',
  type: 'Sample',
  value: '0.2',
  subtype: 'LOAD',
}
Suggest Edits

/events/machine/timeline

 

The timeline socket provides the following events and commands. Each is described in more detail in its own section.

Event
Description

update

Fires in response to a send_metrics request or when new data is available. Carries sample data.

Command
Description

get_metrics

Requests sample data for a set of metrics on a machine over a given time range.

const socket = io('https://api.machinemetrics.com/events/machine/timeline');

socket.on('connect', () => {
  socket.emit('join', {
    token: 'access-token',
  });
});

socket.on('channel_error', (e) => {
  console.error('channel_error', e);
});

socket.on('channel_join_success', () => {
  console.log('channel_join_success');
});

socket.on('channel_join_failure', (e) => {
  console.error('channel_join_failure', e);
});

socket.on('update', (data) => {
  console.log(data);
});

socket.open();

get_metrics Command

The get_metrics command takes a single argument, which is an object describing your request. The table below describes the structure of this object.

Parameter
Description

machineId

The id of the machine to request data for.

requestId

An arbitrary value that will be handed back in an update response, so that you can match the response to the appropriate request.

startAt

The start of the time range to look up data for as an ISO-formatted date-time string.

endAt

The end of the time range to look up data for as an ISO-formatted date-time string.

metrics

An array of one or more objects describing individual metrics to query.

The metricInfo objects are described in the next table.

Parameter
Description

key

The name of a raw data metric emitted by a machine. Some additional keys may be synthesized by MachineMetrics.

type

The type of a data metric as defined in the MachineMetrics data items table.

subtype

The subtype of a data metric, if applicable, as defined in the MachineMetrics data items table.

tag

An arbitrary tag for this requested metric. The corresponding response data in the update event will be keyed by this value.

The key, type, and subtype parameters are optional, but key or type must be present. All three of these parameters can be passed as a single string or as an array of multiple values. When multiple values are provided, samples matching any of the values will be included in the result set.

const machineId = 'machine-id-abc';
const startAt = '2017-06-01T00:00:00Z';
const endAt = '2017-06-08T00:00:00Z';

// Request a week of program data
socket.emit('get_metrics', {
  machineId,
  startAt,
  endAt,
  metrics: [{
    type: 'Program',
    subtype: ['PROGRAM', 'SUBPROGRAM'],
    tag: 'metricUUID1',
  }],
  requestId: 'request-1',
});

update Event

The update event returns data requested in a previous get_metrics command. One or more samples are sent back in a compound data object.

A sample response object is shown below.

{
  data: {
    metricUUID1: {
      machineId: 'machine-id-abc',
      startAt: '2017-06-01T00:00:00Z',
      endAt: '2017-06-08T00:00:00Z',
      requestId: 'request-1',
      metrics: {
        type: 'Program',
        subtype: ['PROGRAM', 'SUBPROGRAM'],
        tag: 'metricUUID1',
      },
      data: [{
        key: 'pprogram',
        value: 'p01.12345',
        type: 'Program',
        subtype: 'PROGRAM',
        startUnixMs: 1522281871.774,
      }, {
        key: 'pprogram',
        value: 'p02.13579',
        type: 'Program',
        subtype: 'PROGRAM',
        startUnixMs: 1522281963.351,
      }],
    },
  },
}

Every response object is keyed with data at the root. The data object contains one or more objects each keyed by a metric's tag from the get_metrics request. These objects contain a copy of all the parameters originally sent with the corresponding get_metrics request: machineId, requestId, startAt, endAt, and metrics. The last parameter, data, is an array with the actual sample data. This object is described in the below table.

Parameter
Description

key

The name of a raw data metric emitted by a machine.

type

The type of a data metric as defined in the MachineMetrics data items table.

subtype

The subtype of a data metric, if applicable, as defined in the MachineMetrics data items table.

value

The sample value.

startUnixMs

The exact time that the sample or event was generated on the machine. Represented as a unix millisecond timestamp.

Suggest Edits

/events/machine/status

For client applications that require real-time information on changes to machine status, the status channel should be used.

 

In addition to the core events and commands available on all sockets, the status socket adds the following:

Event
Description

update

Fires when a machine's status changes.

channel_error_status

Fires when an error occurs specific to the status channel.

Command
Description

set_machines

Invoked after the channel is joined to provide the set of machines that will be reported on. set_machines can be called multiple times to update the set of machines. Must provide a JSON array of machine IDs.

Once set_machines is called, update is called once for every machine that is being managed by the channel. After the current value for each of those metrics have been reported, the update event will only be fired when changes to those values occur.

A machine can be reported with the following status values:

Status Value
Description

UNAVAILABLE

The machine is turned off or not accessible by the monitoring system.

ACTIVE

The machine is currently executing a program.

INACTIVE

The machine is stopped, idle, or otherwise not actively producing.

FAULT

One or more faults are active on the machine. It may or may not be actively producing.

const socket = io('https://api.machinemetrics.com/events/machine/status');

socket.on('connect', () => {
  socket.emit('join', {
    token: 'access-token',
  });
});

socket.on('channel_error', (e) => {
  console.error('channel_error', e);
});

socket.on('channel_join_success', () => {
  console.log('channel_join_success');
  socket.emit('set_machines', [
    'MACHINE_ID1',
    'MACHINE_ID2',
    'MACHINE_ID3',
  ]);
});

socket.on('update', (data) => {
  console.log(data);
});

socket.on('channel_join_failure', (e) => {
  console.error('channel_join_failure', e);
});

socket.open();

Data Structure for update Event Payload

{
  machineId: 'MACHINE_ID1',
  timestamp: '2018-01-03 20:43:08.132+00:00',
  status: 'FAULT',
  message: 'fault message',
  faults: [{
    key: 'system',
    type: 'Condition',
    value: 'FAULT',
    timestamp: '2018-01-03 20:43:08.132+00:00',
  }],
}

The message and faults properties are only returned when a machine is in a fault state.