Open Azumuta App pages from another application

Updated

Note: This article is technical, so we recommend involving someone with the right technical expertise. If you have questions or need help with the setup, contact support@azumuta.com.

Another application, such as an ERP system, an MES or a Microsoft Power Apps canvas app, can open a page of the Azumuta App in a browser. For example, a button in your application opens the work instruction for the current order. The page signs the operator in with a one-use session token.

Sign in with a session token

  1. Your integration requests a session token with POST /api/v1/auth/sessionTokens. It sends the API key of an API device with the Session tokens scope in the x-api-key header. The body names the operator (loginIdentifier) and the normal device the page runs on (deviceId).
  2. Your application opens the page URL with the token in the sessionToken query parameter.
  3. The page signs the operator in on that device and removes the token from the address bar.

A session token works only once and expires after 60 seconds. Request a new token each time your application opens a page. Do not put the API key in the page URL.

The page uses the settings of the normal device, for example Instruction step list is closed by default and Automatically open on first instruction step. To change these, edit the device.

For a complete example with the device setup, see Connect Microsoft Power Apps to Azumuta with device API tokens. For the request and response, see the in-app REST API documentation.

Pages

Page path Opens
/workinstruction/WORK_INSTRUCTION_ID A standalone work instruction preview. Answers and completion are not saved as a recording.
/view/WORK_INSTRUCTION_ID A work instruction for consultation. Normally creates a consultation recording; if consultation recording is disabled for the instruction, opens a standalone preview instead.
/recording/RECORDING_ID An existing recording
/product/PRODUCT_ORDER_NUMBER A product order, identified by its order number
/article/ARTICLE_NUMBER An article preview, identified by its article number
/article/default/ARTICLE_CATEGORY_ID A preview of the default article of an article category
/spot?treeNodeId=TREE_NODE_ID A spot, identified by its tree node ID

To record execution, open an existing recording with /recording/RECORDING_ID, or open the product order with /product/PRODUCT_ORDER_NUMBER and select its work instruction.

Put the path after the host of your workspace and replace the placeholders. Use the Work instruction ID, not the Tree node ID. See Using your data in the REST API to find the IDs.

Add the session token and the options below as query parameters. Start the first parameter with ? and each next parameter with &. URL-encode each value. For example:

https://YOUR_AZUMUTA_HOST/recording/RECORDING_ID?sessionToken=SESSION_TOKEN
https://YOUR_AZUMUTA_HOST/spot?treeNodeId=TREE_NODE_ID&sessionToken=SESSION_TOKEN

The operator must have access to the content the page opens.

Options for all pages

Parameter Value Effect
sessionToken A session token Signs the operator in. Required.
virtualKeyboard true Shows an on-screen keyboard when the operator selects a text field. Use this on touchscreens without a keyboard.
bgColor A hex color, for example %23004080 Sets the background color of the top bar. Encode # as %23.
fgColor A hex color, for example %23FFFFFF Sets the text color of the top bar.
rightButtonsOffset A number of pixels Moves the buttons on the right of the top bar to the left. Use this when your application shows its own content in that corner, such as a close button.
fastForward false Turns off fast forward.

Options per page

Work instruction and consultation

These options apply to /workinstruction/... and /view/....

Parameter Value Effect
version A version index Opens that version instead of the latest approved version. The index starts at 0, so version=9 opens version 10.
backButtonUrl An http or https URL Shows a back button in the top bar. The button opens this URL.
closeWindowOnFinish true When the operator finishes, the page opens backButtonUrl. Without backButtonUrl, the page closes its browser tab, but only if a script opened that tab.

These options apply to /workinstruction/... only:

Parameter Value Effect
variants Variant codes, separated by commas Shows the work instruction for these variants.
parameters A JSON object with parameter values Gives values to the parameters in the work instruction, the same as the parameters of a product order.

Recording

Parameter Value Effect
backButtonUrl An http or https URL Shows a back button in the top bar. The button opens this URL.
closeOnFinish true When the operator finishes, the page opens backButtonUrl. Without backButtonUrl, the page closes its browser tab if a script opened that tab. Otherwise it asks the operator to close the tab.
spotId A spot ID Links issues that the operator creates during the recording to this spot.

Spot

Parameter Value Effect
treeNodeId The tree node ID of a spot Opens this spot. Required.
defaultTab explore, audits, articles, products or asset-tasks Opens this tab first. The default is explore.

The product order page and the article pages have no other options.