Postman Collections

The Business Intelligence (BI) API Postman collection contains predefined API requests and provides easy access to all available Oracle MICROS Simphony BI API endpoints. It follows the same API categorization as described in this document. Use the collection as templates when developing new integrations.

The collection uses the built-in OAuth2 workflow in Postman to get an auth token. Oracle recommends to only use the manual authentication workflow described in Alternative Authorization and Authentication below if necessary or to manually complete individual authorization and authentication steps.

Prerequisites

• Download and import both collections into Postman.

• Create a BI API account. See Adding API Accounts for more details.

• Collect all required information needed to authorize and authenticate. See Send Requests for more details.

• Go to Environments in Postman and update all environment variables with the env_ prefix with the information collected from the previous bullet.

  • Environment variables with the auth_env_ prefix only need to be updated when using the manual authentication workflow.

  • Environment variables with the auto_ prefix do not need to be updated. The collections will automatically update those variables.

Tip:

Remember to save the environment settings after changing the values.

How to Use Collections

Follow these steps:

• After populating the environment variables, select the collection's name to open it.

• Make sure the correct environment is selected using one of the following methods:

  • Click the check mark icon on the environment:

    

  • Select the environment from the top right corner drop-down after selecting the collection's name:

    

• Scroll to the bottom of the Authorization tab and then click Get New Access Token.

  

• The Reporting and Analytics sign in page opens in a new browser window. Enter the API account credentials and then click Sign In.

  Note:

  Use API account credentials to authenticate. Do not use Reporting and Analytics credentials.

• After a token is successfully retrieved, click Proceed.

• Optionally, provide an alternative name for the token and then click Use Token. This helps when switching between different accounts or different environments when testing.

• Now all BI API endpoints can be used.

Examples

The collection includes several examples for search and include parameters and for the getGuestChecks endpoint. See Search and Include for more details.

The examples for the searchCriteria include generic data and are just examples. For these examples to work in a particular environment, the numbers, dates, or names used must be updated with actual data.

The example for the real-time checks collection will get the checks for the last 30 minutes when run for the first time or run for the first time for the current date. Afterwards, it will continue to return checks that were opened or closed since the last time the API was called. The details are stored within environment variables. Check the logging in the Postman console for the date and times being used.

Alternative Authorization and Authentication

The collection has predefined calls in the Manual Authentication workflow folder that you can use to individually run calls to authorize, authenticate, get, and refresh an auth token. See Authenticate for more details.

Oracle Food and Beverage recommends using the Postman built-in OAuth2 workflow. To use the manual workflow, send the request in the following order:

1. Authorize

2. Sign In

   Make sure the environment variables auth_env_username, auth_env_password, and env_orgIdentifier are set, and then send the request.

   After a successful response, the auto_auth_env_authCode environment variable is set.

3. OAuth Token

   After a successful response, the following environment variables are set:

   • auto_auth_env_token is set to the bearer token to use on a request.

   • auto_auth_env_refreshToken is set to a token used on the refresh request.

To refresh a token before it expires (13 days after it was issued), send the OAuth Token (Refresh) request.

After a successful response, the following environment variables are set:

• auto_auth_env_token is set to the bearer token to use on a request.

• auto_auth_env_refreshToken is set to a token used on the refresh request.

After getting an OAuth token, copy the current contents of the auto_auth_env_token environment variable. Then navigate to the collection name, click the Authorization tab, and in the Current Token section copy the token into the Token field.

Download Collections

Tip:

To download the collection JSON, right-click the collection name and then save the collection to your computer.

The following table describes collection templates.

Collection Name	Description	Version and Date Last Updated
Oracle MICROS Simphony BI API Environment Variables	Template with environment-specific details and variables for requests. The collection includes instructions for each variable plus where and how to find the values to populate.	1.2: May 2024 1.1: October 2023 1.0: August 2023 (initial publishing)
Oracle MICROS Simphony Business Intelligence API	Template with request details for every BI API endpoint. Review How to Use Collections for more details.	1.2: May 2024 1.0: August 2023 (initial publishing)