Skip to main content
Documentation Powered by Redocly

REST Documentation (1.0.0)

The MachineMetrics REST APIs are a set of endpoints that can be used for generating historical reports, downloading CSVs of those results, and pushing data into MachineMetrics from other systems like ERPs.

Production

Production queries are the highly powerful mechanism that is used to drive much of the reporting in the MachineMetrics application including the Report Builder.

With the ability to query for various KPIs such as OEE, Downtime, and Quality including their subcomponents across large spans of time, you can use this API to integrate with various Business Intelligence tools. Use this endpoint to watch for historical trends, address high impact reasons for downtime, and make sure you're meeting your production standards.

Get Production Query Results

Retrieve selected data metrics rollups for a given time frame.

Authorizations:
bearerAuth
Request Body schema: application/json

Production Query Object

startDay
required
string <date>

Must be a valid ISO 8601 date format (e.g., "2017-07-19"); startDay must be before or equal to endDay

endDay
required
string <date>

Must be a valid ISO 8601 date format (e.g., "2017-07-19"); endDay must be after or equal to startDay

required
Array of objects

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" } ]
Array
metric
string
Enum: "actualPartTime" "allTime" "availability" "averagePartsPerHour" "categorizedDowntime" "downtime" "expectedPartsPerHour" "expectedPartTime" "expectedSetupTime" "goodParts" "idealPartsPerHour" "idealPartTime" "inCycleIdealParts" "maxEndTime" "minStartTime" "nonOptionalTime" "nonconformParts" "nonconformRate" "oee" "oeeFailureThreshold" "oeeWarningThreshold" "ooe" "partsGoal" "partsGoalFailureThreshold" "partsGoalWarningThreshold" "performance" "plannedDowntime" "productionDowntime" "productionTime" "productionTimeInCycle" "quality" "rejectRate" "rejectedParts" "scheduledExpectedParts" "scheduledIdealParts" "scheduledRejectedParts" "scheduledTime" "scheduledTimeInCycle" "scheduledTotalParts" "scrapRate" "scrappedParts" "setupTime" "teep" "timeInCut" "timeInCycle" "timeSpindleRotating" "totalPartTime" "totalParts" "uncategorizedDowntime" "unplannedDowntime" "unscheduledTime" "utilizationFailureThreshold" "utilizationRate" "utilizationWarningThreshold"
metric notes
actualPartTime Average in-cycle time to make each part
allTime Sum of all time (ms)
availability Rollup of availability across all included machines
averagePartsPerHour Average number of parts created each hour over scheduled time
categorizedDowntime Sum of categorized machine downtime (ms)
downtime Sum of all machine downtime (ms)
expectedPartsPerHour The expected number of parts that would be created each hour over scheduled time
expectedPartTime Maximum amount of time a given part is expected to take for any one jobOperation (ms)
expectedSetupTime Sum of time expected to be spent in setup (ms)
goodParts Sum of all parts not rejected
idealPartsPerHour The most parts that could ideally be created each hour over scheduled time
idealPartTime Maximum amount of time a given part can ideally take for any one jobOperation (ms)
inCycleIdealParts 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.
maxEndTime Latest time that a job operation was active
minStartTime Earliest time that a job operation was active
nonOptionalTime Sum of all time excluding optional shifts (ms)
nonconformParts The number of total parts that were rejected as non-conforming
nonconformRate Percentage of parts produced that were rejected as non-conforming
oee Rollup of OEE across all included machines
oeeFailureThreshold Percent threshold (as value between 0 and 1) below which OEE would be in failure state
oeeWarningThreshold Percent threshold (as value between 0 and 1) below which OEE would be in warning state
ooe Rollup of OOE across all included machines
partsGoal Weighted percent (as a value between 0 and 1) of parts created out of the set part goals.
partsGoalFailureThreshold Percent threshold ( as value between 0 and 1) below which parts goal would be in failure state
partsGoalWarningThreshold Percent threshold (as value between 0 and 1) below which parts goal would be in warning state
performance Rollup of performance across all included machines
plannedDowntime Sum of all machine downtime that was planned (ms)
productionDowntime Sum of time when machines were in production but not in cycle (ms)
productionTime Sum of all time when machines were in production (ms)
productionTimeInCycle Sum of time in cycle when machines were in production (ms)
quality Rollup of quality across all included machines
rejectRate Percentage of parts made that were rejected
rejectedParts Sum of parts rejected
scheduledExpectedParts Total expected parts to be made during unplanned setup and production.
scheduledIdealParts 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.
scheduledRejectedParts Sum of parts rejected when machines were scheduled and not in setup
scheduledTime Sum of all time when machines were scheduled and not in setup (ms)
scheduledTimeInCycle Sum of time in cycle when machines were scheduled and not in setup (ms)
scheduledTotalParts Sum of all parts produced when machines were scheduled and not in setup
scrapRate 1 - quality
scrappedParts The number of total parts that were rejected as scrap
setupTime Sum of all time when machines were in setup (ms)
teep Rollup of TEEP across all included machines
timeInCut Sum of time when machines were cutting (ms)
timeInCycle Sum of time in cycle (ms)
timeSpindleRotating Sum of time when machine spindles were rotating (ms)
totalPartTime Average total time to make each part, including loading/unloading
totalParts Sum of all parts produced
uncategorizedDowntime Sum of uncategorized machine downtime (ms)
unplannedDowntime Sum of all machine downtime that was unplanned (ms)
unscheduledTime Sum of all time when machines were unscheduled (ms)
utilizationFailureThreshold Percent threshold (as value between 0 and 1) below which utilization would be in failure state
utilizationRate Percent (as value between 0 and 1) of queried the queried time that machines have been in cycle
utilizationWarningThreshold Percent threshold (as value between 0 and 1) below which utilization would be in warning state
Array of objects

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.

Array
group
string
Enum: "machine" "machineGroup" "jobOperation" "jobOperationRun" "operator" "hour" "shift" "day" "week" "month" "quarter"

Note that for time-based groupings such as hour, shift, day, week, month, and quarter, there are limitations.

hour cannot be used with any other time-based grouping. week cannot be used with month or quarter.

item notes
machine groups and aggregates selected data metrics by individual machine rollup (e.g. "citizen 1", "star 4" etc.)
machineGroup groups and aggregates selected data metrics by machine group rollup (e.g. "cell 1", "mazak" etc.)
jobOperation groups and aggregates selected data metrics by jobOperation rollup (e.g. "screw", "bolt" etc.)
jobOperationRun groups and aggregates selected data metrics by jobOperationRun rollup (e.g. a specific run of a jobOperation with a start and end date)
operator groups and aggregates selected data metrics by operator
hour 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 groups and aggregates selected data metrics by shift rollup (e.g. "first shift", "second shift" etc.)
day groups and aggregates selected data metrics by day (e.g., "8/1/17", "8/2/17"... "8/20/17")
week groups and aggregates selected data metrics by week (e.g., "7/31/17 - 7/7/17", ... "8/21/17 - 8/28/17")
month groups and aggregates selected data metrics by month (e.g. "1/1/2018 - 1/31/2018", ... "2/1/2018 - 2/28/2018")
quarter groups and aggregates selected data metrics by quarter (e.g. "1/1/2017 - 3/31/2017", ... "4/1/2017 - 6/30/2017")
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.

machine
Array of strings <uuid>

Array of string machineIds

machineGroup
Array of strings <uuid>

Array of string machineGroupIds

jobOperation
Array of strings <uuid>

Array of string jobOperationIds

shift
Array of strings <uuid>

Array of string shiftIds

operator
Array of strings <uuid>

Array of string operatorIds

csv
boolean

When true, will provide a download link (and expiry) for csv. Must append a user-token to the link in order to download.

See operations for JWT generation and jwtAuth securities definition for more information.

flatten
boolean

When true, the items array will contain the deepest leaves with any entity information applied to every item.

Responses

Request samples

Content type
application/json
{
  • "start": "2017-07-19T10:00:00Z",
  • "end": "2017-07-21T10:00:00Z",
  • "data": [
    ],
  • "groupBy": [
    ],
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "range": {
    },
  • "aggregate": {
    },
  • "entities": {
    },
  • "items": [
    ]
}

Get Production Results CSV

Retrieve the results of a production metrics rollup request in CSV format.

Authorizations:
jwtAuth
path Parameters
resourceId
required
integer

Dynamic resource ID for CSV download path - resource expiry date is specified alongside resource ID in response body.

query Parameters
token
required
string <password>
localize
boolean
Default: false

Option that enables the following CSV formatting options:

  • localize all date-times with the company timezone offset, instead of using UTC
  • format durations as hh:mm:ss.ms strings, instead of using integer millisecond counts
  • map column headers to their associated report builder names

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_token",
  • "error_description": "Invalid token: access token is invalid"
}

Downtime

Downtime queries are great for building downtime paretos, but can also be leveraged to watch for trends in your downtime reasons over time. Grouping your data by shift and other details like the operation running on the machine can provide deeper insight into where your bottlenecks are.

Get Downtime Query Results

Retrieve downtime (ms) rollups for a given time frame.

Authorizations:
bearerAuth
Request Body schema: application/json

Downtime Query Object

start
required
string <date-time>

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

end
required
string <date-time>

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

Array of objects

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 usage:

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.

Array
group
string
Enum: "machine" "machineGroup" "jobOperation" "shift" "reason" "day" "week" "plannedState"
item notes
machine groups and aggregates downtimeMs by individual machine rollup (e.g. "citizen 1", "star 4" etc.)
machineGroup groups and aggregates downtimeMs by machine group rollup (e.g. "cell 1", "mazak" etc.)
jobOperation groups and aggregates downtimeMs by jobOperation rollup (e.g. "screw", "bolt" etc.)
shift groups and aggregates downtimeMs by shift rollup (e.g. "first shift", "second shift" etc.)
reason groups and aggregates downtimeMs by reject reason (e.g., "Bad Part", ... "Broken Tool")
day groups and aggregates downtimeMs by day (e.g., "8/1/17", "8/2/17"... "8/20/17")
week groups and aggregates downtimeMs by week (e.g., "7/31/17 - 7/7/17", ... "8/21/17 - 8/28/17")
plannedState groups and aggregates downtimeMs by plannedState (e.g., "planned" or "unplanned")
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.

machine
Array of strings <uuid>

Array of string machineIds

machineGroup
Array of strings <uuid>

Array of string machineGroupIds

jobOperation
Array of strings <uuid>

Array of string jobOperationIds

shift
Array of strings <uuid>

Array of string shiftIds

reason
Array of strings <uuid>

Array of string reasonIds

plannedState
Array of strings
Items Enum: "planned" "unplanned"

Array of string plannedStates - valid states are planned and unplanned

csv
boolean

When true, will provide a download link (and expiry) for csv. Must append a user-token to the link in order to download.

See operations for JWT generation and jwtAuth securities definition for more information.

flatten
boolean

When true, the items array will contain the deepest leaves with any entity information applied to every item.

Responses

Request samples

Content type
application/json
{
  • "start": "2017-07-19T10:00:00Z",
  • "end": "2017-08-19T10:00:00Z",
  • "groupBy": [
    ],
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "range": {
    },
  • "aggregate": {
    },
  • "entities": {
    },
  • "items": [
    ]
}

Get Downtime Results CSV

Retrieve the results of a downtime metrics rollup request in CSV format.

Authorizations:
jwtAuth
path Parameters
resourceId
required
integer

Dynamic resource ID for CSV download path - resource expiry date is specified alongside resource ID in response body.

query Parameters
token
required
string <password>

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_token",
  • "error_description": "Invalid token: access token is invalid"
}

Quality

Quality queries give you the power to generate paretos that help you see where your biggest wastes are when it comes to scrap and non-conform pieces. Rejects can be grouped by reason, machine, shift, and even the operation the rejected part was for. Query for totals to build a downtime pareto, or look for trends by requesting by-day or by-week rollups.

Get Quality Query Results

Retrieve rejectCount rollups for a given time frame.

Authorizations:
bearerAuth
Request Body schema: application/json

Quality Query Object

start
required
string <date-time>

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

end
required
string <date-time>

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

Array of objects

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 usage:

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

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

Array
group
string
Enum: "machine" "machineGroup" "jobOperation" "shift" "reason" "day" "week"
item notes
machine groups and aggregates rejectCount by individual machine rollup (e.g. "citizen 1", "star 4" etc.)
machineGroup groups and aggregates rejectCount by machine group rollup (e.g. "cell 1", "mazak" etc.)
jobOperation groups and aggregates rejectCount by jobOperation rollup (e.g. "screw", "bolt" etc.)
shift groups and aggregates rejectCount by shift rollup (e.g. "first shift", "second shift" etc.)
reason groups and aggregates rejectCount by reject reason (e.g., "Bad Part", ... "Broken Tool")
day groups and aggregates rejectCount by day (e.g., "8/1/17", "8/2/17"... "8/20/17")
week groups and aggregates rejectCount by week (e.g., "7/31/17 - 7/7/17", ... "8/21/17 - 8/28/17")
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.

machine
Array of strings <uuid>

Array of string machineIds

machineGroup
Array of strings <uuid>

Array of string machineGroupIds

jobOperation
Array of strings <uuid>

Array of string jobOperationIds

shift
Array of strings <uuid>

Array of string shiftIds

reason
Array of strings <uuid>

Array of string reasonIds

csv
boolean

When true, will provide a download link (and expiry) for csv. Must append a user-token to the link in order to download.

See operations for JWT generation and jwtAuth securities definition for more information.

flatten
boolean

When true, the items array will contain the deepest leaves with any entity information applied to every item.

Responses

Request samples

Content type
application/json
{
  • "start": "2017-07-19T10:00:00Z",
  • "end": "2017-08-19T10:00:00Z",
  • "groupBy": [
    ],
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "range": {
    },
  • "aggregate": {
    },
  • "entities": {
    },
  • "items": [
    ]
}

Get Quality Results CSV

Retrieve the results of a quality metrics rollup request in CSV format.

Authorizations:
jwtAuth
path Parameters
resourceId
required
integer

Dynamic resource ID for CSV download path - resource expiry date is specified alongside resource ID in response body.

query Parameters
token
required
string <password>

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_token",
  • "error_description": "Invalid token: access token is invalid"
}

CSV Auth

Operations for authenticating CSV download requests.

get JWT for CSV Auth

With the JWT you receive in this response, you can authenticate requests to download various CSV reports.

To do so, first hit any of the above report endpoints with csv: true in the request body. The response will have a property csv: { url: exampleUrl, expires: date }.

To download the CSV report, simply append the JWT to the exampleUrl like so:

https://exampleUrl?token={{JWT}}

Endpoint Example Usage

First, hit the endpoint for the report that supports CSV format.

CSV Report Request Body
{
  "start":"2019-05-01T00:00:00Z",
  "end":"2019-05-05T00:00:00Z",
  "data": [
    {"metric":"timeInCycle"}
  ],
  "groupBy":[
    {"group":"day"},
    {"group":"machine"}
  ],
  "filter": {
    "machine": ["6fe43f3a-5415-49bf-8830-549ca55b78ea", "e823053c-05b7-4a39-9e1a-0858e44c4284", "f076a4cf-f308-443a-9df7-2b4d68dd7c58"]
  },
  "csv": true
}
CSV Report Response Body
{
    "range": {
        "start": "2019-05-01T00:00:00.000Z",
        "end": "2019-05-05T00:00:00.000Z"
    },
    "csv": {
        "url": "https://api.machinemetrics.com/csv/production/{{resourceId}}",
        "expires": "2019-09-18T00:00:00.000Z"
    },
    "aggregate": {
        "timeInCycle": 1060874083
    },
    "entities": {...},
    "items": [{...},{...}]
}

This will generate a CSV report that you will be able to request using a JWT for added security. Now send a GET request to /user-token to receive a user-token JWT response. To download the CSV report, simple append the {{JWT}} to the CSV url like so:

https://api.machinemetrics.com/csv/production/{{resourceId}}?token={{JWT}}

Note that some of the CSV endpoints allow for additional configuration options via query parameters, such as localize for the production report CSV request.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

ERP

Operations for ERP system integration.

See our simple-erp-integration GitHub repo for a full example.

Start job run

Starts a new job run on a machine.

Authorizations:
bearerAuth
Request Body schema: application/json
erpJobOperationRunId
required
string

Unique ID used by the ERP to identify this job run.

erpMachineId
required
string

Unique ID used by the ERP to represent the machine for this job run.

jobName
required
string

The name of the associated job in MachineMetrics.

operationName
string or null
Default: ""

The name of the associated operation in MachineMetrics. Default value is an empty string.

lotName
string or null
Default: ""

The name of the associated lot in MachineMetrics. Default value is an empty string.

partName
string or null
Default: ""

The name of the associated part in MachineMetrics. Default value is an empty string.

startInSetup
boolean
Default: false

If true, the job run will be started in setup; otherwise it will be started in production.

startAt
string or null <date-time>
Default: null

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").

jobOperationDescription
string or null
Default: null

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

quantityRequired
integer or null
Default: null

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

expectedSetupTime
integer or null (seconds)
Default: null

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
integer or null (milliseconds)
Default: null

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
integer or null (milliseconds)
Default: null

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

Responses

Request samples

Content type
application/json
{
  • "erpJobOperationRunId": "01",
  • "erpMachineId": "2",
  • "startInSetup": false,
  • "startAt": "2017-10-10T10:11:00.000Z",
  • "jobName": "Spacely Sprockets",
  • "jobOperationDescription": "Sprockets for Spacely Space Sprockets, Inc.",
  • "lotName": null,
  • "partName": "Sprocket001",
  • "quantityRequired": 1000,
  • "expectedSetupTime": 600,
  • "expectedPartTime": 120000,
  • "idealPartTime": 100000
}

Response samples

Content type
application/json
null

Get job run

Gets data for a specified job run.

Authorizations:
bearerAuth
query Parameters
erpRunId
required
string

Specified job run ERP ID

Responses

Response samples

Content type
application/json
{
  • "startAt": "2017-03-09T18:20:18.000Z",
  • "endAt": null,
  • "metrics": {
    }
}

Stop job run

Stops a job run on a machine.

Authorizations:
bearerAuth
Request Body schema: application/json
erpJobOperationRunId
required
string

Unique ID used by the ERP to identify this job run.

endAt
string or null <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.

Responses

Request samples

Content type
application/json
{
  • "erpJobOperationRunId": "01",
  • "endAt": "2017-10-10T10:11:00.000Z"
}

Response samples

Content type
application/json
null

Jobs Import

Operations for importing jobs.

Import jobs via file

Creates jobs from list via file - format is specified in request.

Authorizations:
bearerAuth
query Parameters
type
string
Default: "mm"
Enum: "mm" "inforVisual" "inforLN"

The format of the jobs file being imported.

Acceptable values are mm, inforVisual, and inforLN.

Format String Description
mm (default) The default format: a CSV file formatted as specified here
inforVisual A jobs CSV exported from Infor VISUAL
inforLN A jobs XLSX file exported from Infor LN

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 template, here.

Request Body schema: multipart/form-data
csvFile
required
string <binary>

The CSV file being imported.

autoArchive
boolean
Default: false

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

Responses

Response samples

Content type
application/json
null