Using our API


Click on the main menu icon in the upper left corner of Andon App and select ‘Select org’

4a.png
 

Click the dropdown and choose the org you want to access

4.png
 

To go to the ‘settings’ page, click on the main menu icon in the upper left corner of the site and select ‘Settings’

Note: Only certain auth levels have access to the ‘Settings’ page.  If you do not see ‘Settings’ on the main menu contact your site administrator

 

On the settings page, push the ‘API TOKENS’ button

6.png
 

This is the page for creating and deleting API tokens for your org.  These tokens are used to authenticate API posts that are made to your org- without the token in the API call the app not accept data.  API tokens are treated as a ‘user’ for the org meaning they are billed at the standard user rate.  You can generate as many tokens as are needed for your org

To generate a new token push the ‘GENERATE API TOKEN’ button

 

A popup will appear asking you to name the token.  This is for you to remember what the token is used for, and also serves as the user ‘name’ in all reporting for production data that is generated.  This name cannot be changed after the token is created

Once a name is entered push the ‘GENERATE’ button

8.png
 

Another popup will appear with the token itself.  Store this in a safe place as this is the only time the token will be shown to you.  Once you’ve stored the token push the ‘OKAY, I’VE SAVED THE TOKEN’ button

9.png
 

You will be taken back to the ‘api tokens’ page and now the created token will appear on the list.  If at some point you need to delete the token, just select the token and click the trash can icon to delete the token

10.png
 

Now that you have a token to authenticate, you can begin to submit valid API calls

There are just 2 API calls used to record production data to your andon site:

  1. A call to record when a unit is produced and indicate if that unit passed or failed, and what the process time was
  2. A call to update the station status to red, yellow, or green and provide the status reason and notes

The remaining portion of this guide will outline the requirements for each call, and API responses. 

 

API (1) – Recording production results

The first call is used to record production results.  This is equivalent to the user recording ‘pass’ or ‘fail’ on the collect page in the web app.  This data should be posted to the site in real time rather than in batches as the site will use the post timestamp as part of the metrics.  Below is an example of the call with each element explained in subsequent bullets.  The API can be called from any programming language such as Java, C#, Python, Javascript, and cURL using our SDKs.   For this example we’ve used cURL.  Note that the JSON format will change slightly based on the OS implementation – this example below is shown as implemented in Windows OS. 

curl -H "Content-Type: application/json" -H "Authorization: Bearer [token here]" -X POST -d "{\"orgName\":\"[org name here]\",\"lineName\":\"[line here]\",\"stationName\":\"[station here]\",\"passResult\":\"[p/f here]\",\"processTimeSeconds\":[time here],\"failReason\":\"[reason here]\",\"failNotes\":\"[notes here]\"}" https://portal.andonapp.com/public/api/v1/data/report/

  • [token here] – this is where you insert the token generated from step 9
  • [org name here] – this is where you enter the org name associated with the token (shown right below ‘andon’ in the top bar of the app)
  • [line here] – this is where you enter the line name associated with the station that you are recording data for.  The line name must match exactly to a line name listed in the ‘lines and stations’ settings page.  If a line name is updated in the ‘lines and stations’ settings page the API reference must also be updated
  • [station here] – this is where you enter the station name that you are recording data for. The station name must match exactly to a station name listed in the ‘lines and stations’ settings, and must be associated with the line entered above.
  • [p/f here] – enter PASS or FAIL here to indicate whether the produced unit has passed or failed the production process at that station.  This will feed into the yield calculation for the station
  • [time here] – enter the process time (start to finish) it took to produce the unit, in seconds.  The process time must be greater than or equal to 1 second
  • [reason here] – This field is only required when FAIL is indicated as the result above.  Here you must provide the fail reason, and the provided text must match exactly to one of the options listed in the ‘organization settings’ page under ‘failure reasons’
  • [notes here] – This field is only required when FAIL is indicated as the result above AND when ‘require failure comment’ is checked in the ‘organization settings’ page.  This is an open text field to add additional notes for the failure

 

API (2) – Updating station status

The second call is used to update station status (red/yellow/green).  This is equivalent to the user updating the station status on the collect page in the web app.  This data should be posted to the site in real time rather than in batches as alert notifications will be sent out for any RED and GREEN status updates.  Below is an example of the call with each element explained in subsequent bullets.  The API can be called from any programming language such as Java, C#, Python, Javascript, and cURL using our SDKs.   For this example we’ve used cURL.  Note that the JSON format will change slightly based on the OS implementation – this example below is shown as implemented in Windows OS. 

curl -H "Content-Type: application/json" -H "Authorization: Bearer  [token here]" -X POST -d "{\"orgName\":\"[org name here]\",\"lineName\":\"[line here]\",\"stationName\":\"[station here]\",\"statusColor\":\"[status here]\",\"statusReason\":\"[reason here]\",\"statusNotes\":\"[notes here]\"}" https://portal.andonapp.com/public/api/v1/station/update

  • [token here] – this is where you insert the token generated from step 9
  • [org name here] – this is where you enter the org name associated with the token (shown right below ‘andon’ in the top bar of the app)
  • [line here] – this is where you enter the line name associated with the station that you are recording data for.  The line name must match exactly to a line name listed in the ‘lines and stations’ settings page.  If a line name is updated in the ‘lines and stations’ settings page the API reference must also be updated
  • [station here] – this is where you enter the station name that you are recording data for. The station name must match exactly to a station name listed in the ‘lines and stations’ settings, and must be associated with the line entered above.
  • [status here] – enter RED or YELLOW or GREEN to indicate the updated status for the station.  This will feed into the metrics reporting as well as the alert notifications
  • [reason here] – This field is only required when RED or YELLOW is indicated as the result above.  Here you must provide the red/yellow light reason, and the provided text must match exactly to one of the options listed in the ‘organization settings’ page under ‘red/yellow light reasons’
  • [notes here] – This field is only required when ‘require red/yellow/green light comment’ is checked in the ‘organization settings’ page.  This is an open text field to add additional notes for the status update.  This feeds into the notifications and production status reporting

 

API Responses

After an API call is sent the app will provide a response.  There are a variety of responses that can be returned, but in general a response with http status code 200 indicates success and one with 4xx/5xx indicates fail.  Typically a fail response will be formatted as shown below (with example values for errorType and errorMessage):

  • {"errorType":"INVALID_REQUEST","errorMessage":"'RED2' is not a valid status color."}
  • {"errorType":"UNAUTHORIZED_REQUEST","errorMessage":"You do not have permission to use org 'OrgNameHere'."}

The current range of values for errorType is:

  • BAD_REQUEST
  • INVALID_REQUEST
  • RESOURCE_NOT_FOUND
  • UNAUTHORIZED_REQUEST
  • INTERNAL_ERROR

In cURL a success response will be ‘{}’


Still have questions?  We are here to help - contact us