SOP-42Q-MES0098 MES API-42Q Account Services

42Q Home > Tools > 42Q MES API

 

Tools 42Q MES API Version MES15.3.3 Portal 1.0 Work Instruction 

 

This Work Instruction is 42Q's corporate standard.  This document is under revision control. The latest revision is located on Intranet.  Once printed it is an uncontrolled copy. All alterations to this work instruction require approval.  Contact the IT Global Education and Training Department to submit suggested alterations and or updates.

This edition applies to MES15 Portal 1.0 and all subsequent releases and modifications until otherwise indicated in new revisions.

 

 

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:

https://42qmes1.42-q.com:8081/mes-api/api_test_target/documents/work-instructions/a_sample_unit/a_sample_process

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.

1. 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
2. “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.
3. 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.

1. The URL for Nokia’s GOPS project will be similar to this: https://42qconduit1.42-q.com:18004/conduit
2. 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.
3. 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.
4. 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"}

 

---