SOP-42Q-MES0098 MES API-42Q Account Services
42Q Home > Tools > 42Q MES API
This edition applies to MES15 Portal 1.0 and all subsequent releases and modifications until otherwise indicated in new revisions.
Contents
- 1 Purpose
- 2 Usage
- 3 Security
- 4 API Resources
- 5 API Data Import Instructions
- 6 Document Revision History
Purpose
Document externally accessible endpoints into the 42Q MES system.
Usage
Unless otherwise specified all resource URI’s are designed to work with standard HTTP/HTTPS GET requests. The immediate focus of this set of API endpoints is retrieval of production data versus manipulation of said data.
Security
Typically each of these endpoints is secured via our api security package. This package requires each request to be signed by a registered client. Client registrations are provided to all approved API consumers. When authorization is enabled API calls require a properly formatted Authorization header in the HTTP/HTTPS request. The signature algorithms and format are described here though we recommend using pre-packaged libraries maintained and provided by 42q engineering teams.
API Resources
Currently, all of these resources return a standardized JSON result with three top-level attributes:
success: true or false
message: contains an error message if success is false
data: JSON subelement corresponding to the results of the call being made
The base URI for each MES API resource takes the following form:
https://HOSTNAME:PORT/mes-api/target_context
Sub Resources are identified from the base: path/to/resource[?arg1=value1&arg2=value2…] Note: Parameters can be sent in any order as part of the URL as only the name matters--not the location in the URL text.
The following top level resources are currently exposed:
Units Resource
Encapsulates endpoints associated with unit specific data, generally a specific unit serial number. The units resource exposes the following sub-resources assuming the {serialNumber} resource property identifies an existing serial number.
Basic Unit Data
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/units/SAMPLE_UNIT001
Sample Response:
Summary
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/units/SAMPLE_UNIT001/summary
Sample Response:
History
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/units/SAMPLE_UNIT001/history
Sample Response:
Parent Hierarchy
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/units/SAMPLE_UNIT001/parentage
Sample Response:
Child Components
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/units/SAMPLE_UNIT001/children
Sample Response:
Comments
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/units/SAMPLE_UNIT001/comments
Sample Response:
Defects
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/units/SAMPLE_UNIT001/defects
Sample Response:
Route
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/units/SAMPLE_UNIT001/route
Sample Response:
Export Activity/DHR
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/units/export/activity?interval=60
Sample Response:
Shop Orders Resource
Resource exposing endpoints associated with shop orders data.
General Shop Order Data
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/shop-orders/A_SAMPLE_SHOP_ORDER001
Sample Response:
Bill Of Material
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/shop-orders/A_SAMPLE_SHOP_ORDER001/bom
Sample Response:
Attributes Resource
Resource exposing endpoints associated with attributes and the serial numbers related to them.
Attribute Name
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/attributes/A_SAMPLE_ATTR
Sample Response:
{"success": true,"message": "","data": [{"serial_number": "SBSTACK0032.A.017-IC-001","part_number": "PN-ICP0001","shop_order_number": null},{"serial_number": "SBSTACK0032.A.007-IC-021","part_number": "PN-ICP0001","shop_order_number": null},{"serial_number": "SBSTACK0032.A.007-IC-019","part_number": "PN-ICP0001","shop_order_number": null},{"serial_number": "SBSTACK0032.A.007-FEP","part_number": "PN-FEP0001","shop_order_number": null}]}
Attribute Name and Value
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/attributes/A_SAMPLE_ATTR/WITH_ATTR_VALUE
Sample Response:
{"success": true,"message": "","data": [{"serial_number": "SBSTACK0032.A.007-FEP","part_number": "PN-FEP0001"}]}
Parts Resource
Part Info
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/parts/SAMPLE_PART_NUMBER001
Sample Response:
{"success": true,"message": "","data": [{"part_number": "VALBB_BASE1","part_number_exists": true,"part_key": 209,"extended_part_number": "","rev_num": 0,"customer_code": "","family_id": "","country": "USA","label_data": "","prod_line_id": "","product_option": "","model_description": "","product_internal": "","graphic": "","description": "Test Part Number 01","upc": "","weight": 0,"model_number": "","site_id": "","cust_proj_key": 1,"ean": "","height": 0,"length": 0,"pallet_weight": 0,"rohs": "","volume": 0,"width": 0,"obsolete": false}]}
Test Resource
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/test
Sample Response:
{"success": true,"message": "","data": ["Light speed is too slow!"]}
Simple Test
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/test/simple
Sample Response:
{"success": true,"message": "","data": ["This request hasn't been authenticated. However, we are still confident that light speed is too slow!"]}
Containers Resource
A resource dedicated to exposing endpoints associated with containers
Units
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/containers/SAMPLE_CONTAINER_UNIT001/units
Sample Response:
Workstations Resource
Encapsulates endpoints associated with unit specific data, generally a specific unit serial number. The units resource exposes the following sub-resources assuming the {serialNumber} resource property.
All Workstations
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/workstations
Sample Response:
Devices
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/workstations/devices
Sample Response:
Device
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/workstations/devices/A_SAMPLE_DEVICE
Sample Response:
Locations
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/workstations/locations
Sample Response:
Location
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/workstations/locations/A_SAMPLE_LOCATION001 Sample Response:
Processes
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/workstations/processes/SAMPLE_PROCESS
Sample Response:
Process
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/workstations/processes/A_SAMPLE_PROCESS001
Sample Response:
Manufacturing Holds Resource
Resource exposing endpoints associated with manufacturing hold information.
Active
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/mfg-holds/active
Sample Response:
Routes Resource
Resource exposing endpoints associated with routes and sub-routes.
Basic Route
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/routes/SAMPLE_ROUTE001
Sample Response:
Expanded Route Steps
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/routes/SAMPLE_ROUTE001/steps
Sample Response:
Defects Resource
Resource exposing endpoints associated with unit defects
Defect Codes
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/defects/codes
Sample Response:
Defect Code
Sample URI:
https://42qmes1.42-q.com:8081/mes-api/api_test_target/defects/codes/0101
Sample Response:
Documents Resource
Resource exposing endpoints associated with manufacturing documents, including work instructions
Work Instructions
Sample URI:
Response for actual document data {"data" : { "mime_type" : "application/pdf", "document" : "<imagine this is base 64 binary encoded data>", "document_type" : "base64" }, "success" : true, "message" : "This result demonstrates returning an actual document encoded in base64 text"}
Response for a url/link to a document {"data" : { "document" : "http://p88conduit1.sanmina.com:18005/ccr", "document_type" : "url" }, "message" : "This result demonstrates a response to a url instead of an actual document. Generally speaking this message is blank on success. Mime type not provided as it will be returned when accessing the url", "success" : true}
For both of these examples the message is populated even with success == true. Generally speaking this wouldn’t be the case but for the purposes of providing a concise explanation it seemed reasonable here.
API Data Import Instructions
There are currently two types of APIs:
- An API that is specialized for mass imports
- An API that is specialized for transactional data
Bulk Data Imports
For large amounts of data to be imported, there is an import API that is formatted in JSON. There is a function that wraps this data for security purposes, and the way that it is used will depend upon the client architecture.
- The URL for Nokia’s GOPS project will be similar to this: https://42qprtl1.42-q.com/mes-api/nokia_vendor_01/supplier/upstream/import
- “nokia_vendor_01” will be replaced by the client identifier. This will be used to know who is sending the data and what the target should be.
- A simple example follows. This example will record two components for each of the two serial numbers and move them to a specific location.
Request
{
"units":[
{
"unit_id":"5S060000172",
"part_number":"MWKB82-0026-02-16",
"tracking":[
{
"ts":"2017-05-19 18:56:36-05",
"location":"ASSY"
}
],
"components":[
{
"component_id":"MAC ADDRESS",
"ref_designator":"0103FAACE64A"
},
{
"component_id":"MAC ADDRESS",
"ref_designator":"01164D2711D6"
}
]
},
{
"unit_id":"5S060000173",
"part_number":"MWKB82-0026-02-16",
"tracking":[
{
"ts":"2017-05-19 18:56:36-05",
"location":"ASSY"
}
],
"components":[
{
"component_id":"MAC ADDRESS",
"ref_designator":"0103FAACE64B"
},
{
"component_id":"MAC ADDRESS",
"ref_designator":"01164D2711D7"
}
]
}
]
}
Response
{
"success":true,
"message":"Successfully processed data for <2> unit(s)",
"data":[
]
}
Transactional Data
For data to be processed in the standard transactional model, the 42Q Conduit subsystem is employed. This allows for smoother integration and many additional functions compared to the restricted commands available in the bulk import API.
Again, this example does not have the architecture-specific security API, but that will be covered in another document dependent upon the client architecture.
- The URL for Nokia’s GOPS project will be similar to this: https://42qconduit1.42-q.com:18004/conduit
- The client_id is the same that is used in the previous API. The unit_id is the serial number or other identifier of the unit that is being processed.
- A simple example follows. This example will validate the status of the unit, add a comment, and move the unit to the next location in the route from the current “ASSY” workstation.
- The full list of commands and their parameters are available from this web service: http://42qconduit1.42-q.com:18005/ccr
Request
"transactions":[
{
"commands":[
{
"command":{
"name":"AddComment",
"comment_text":"This is a comment."
}
},
{
"command":{
"name":"End"
}
}
],
"unit":{
"unit_id":"5S060000169",
"part_number":"MWKB82-0026-02-16",
"quantity":1
},
"refresh_unit":true
}
],
"source":{
"client_id":"nokia_vendor_01",
"employee":"15475",
"password":"",
"workstation":{
"type":"LOCATION",
"station":"ASSY"
}
},
"version":"1.0",
"token":"",
"keep_alive":false,
"single_transaction":false
}
Response
The response will return both the status of the transaction and the device history record for the unit, including components, attributes, comments, and defects.
{
"source":{
"client_id":"nokia_vendor_01",
"employee":"15475",
"password":"",
"workstation":{
"station":"ASSY",
"type":"Location"
}
},
"status":{
"code":"OK",
"message":""
},
"transaction_responses":[
{
"command_responses":[
{
"command":{
"comment_text":"This is a comment.",
"max_success_status":"PROMPT",
"min_success_status":"EMPTY",
"name":"AddComment"
},
"results":[
{
"message":"Added comment <This is a comment.>",
"status":"OK"
}
],
"status":{
"code":"OK",
"message":"Added comment <This is a comment.>"
}
},
{
"command":{
"max_success_status":"PROMPT",
"min_success_status":"EMPTY",
"name":"End"
},
"results":[
{
"data":{
"action":12,
"action_description":"Failed",
"dept_key":4,
"location_key":5,
"long_workstation":"ASSY Assembly",
"process_key":24,
"sfdc_key":5,
"short_workstation":"ASSY",
"station_type":"0",
"unit_status_key":20,
"user_defined_1":"",
"user_defined_2":""
},
"message":"FAIL to ASSY - <Failed> unit <5S060000169> from <ASSY Assembly> to <ASSY Assembly>",
"status":"OK"
}
],
"status":{
"code":"OK",
"message":"FAIL to ASSY - <Failed> unit <5S060000169> from <ASSY Assembly> to <ASSY Assembly>"
}
}
],
"scanned_unit":{
"status":{
"code":"OK",
"message":"Scanned unit <5S060000169>"
},
"unit":{
"part_number":"MWKB82-0026-02-16",
"quantity":"1",
"unit_id":"5S060000169"
},
"unit_info":{
"auto_commands":null,
"c_level_key":null,
"container_quantity":0,
"container_serial_key":null,
"defect_seq":2,
"description":"ASM FINAL 82-0026-02-16",
"employee_key":4,
"item_num":0,
"loc_ts":"2017-04-20 05:29:07.161581-05",
"location_key":5,
"long_workstation":"ASSY Assembly",
"lot_serial_key":null,
"order_line_key":null,
"part_key":6405,
"part_number":"MWKB82-0026-02-16",
"pass_fail_seq":5,
"process_key":24,
"process_name":"ASSEMBLY",
"quantity":1,
"revision":"",
"route_key":1,
"route_step_key":-1,
"scanning_location_key":5,
"scanning_template":null,
"serial_key":14725,
"serial_number":"5S060000169",
"sfdc_key":5,
"ship_notify_key":null,
"shop_order_key":null,
"shop_order_number":null,
"sit_range_key":null,
"unit_elements":{
"attributes":null,
"comments":[
{
"comment_text":"This is a comment.",
"employee_number":"15475",
"ts":"2017-APR-20 05:29:07 cdt"
}
],
"components":[
{
"component_id":"MAC ADDRESS",
"component_key":82802,
"component_number":2,
"component_part_key":null,
"component_type":0,
"ref_designator":"00164D2711D6",
"removed":0,
"serial_key":14725
},
{
"component_id":"MAC ADDRESS",
"component_key":82801,
"component_number":1,
"component_part_key":null,
"component_type":0,
"ref_designator":"0003FAACE64A",
"removed":0,
"serial_key":14725
}
],
"defects":[
{
"board_loc":null,
"component_key":null,
"defcode_key":65,
"defect_activity_key":207867,
"defect_description":"Solder Balls",
"defect_part":null,
"defect_qty":1,
"defect_seq":2,
"fail_activity_key":207868,
"mfr":"",
"mfr_lot":"",
"pass_fail_seq":4,
"pin1":"",
"pin2":"",
"repair_activity_key":null,
"repair_defcode_key":null,
"repaired":false,
"repaired_nff":0,
"serdef_key":4,
"serial_key":14725,
"surface":"",
"symptom_defcode_key":null
}
]
},
"unit_status":"On The Line",
"unit_status_key":20,
"unit_type":0,
"user_defined":"",
"work_order_key":null
}
},
"status":{
"code":"OK",
"message":""
}
}
],
"version":"1.0"
}
Document Revision History
| Date | Author | Title | Version | Change Reference |
| 07/13/15 | Ashley Martin | Technical Writer | v 1.0 | Document Creation. |
| 12/05/16 | Benjamin Cavanaugh | Technical Writer | v 1.0 | Document Update. |
| 3/1/18 | Martha Jordan | Technical Writer | v 1.0 | Data Import Instructions added. |
