diff --git a/sample-application/baselayer/README.md b/sample-application/baselayer/README.md index d62c4b8..3e5cc09 100644 --- a/sample-application/baselayer/README.md +++ b/sample-application/baselayer/README.md @@ -1,36 +1,33 @@ # Visier Baselayer Sample Application -The `Baselayer` is a sample application that showcases client application interaction with the Visier OAuth 2.0 API without any additional third-party OAuth libraries. It also showcases several API calls to the Visier API built on top of a Next.js application. You must login to your account first. +Baselayer is a Visier sample application that showcases: +* Client application interaction with Visier's OAuth 2.0 client without any third-party OAuth libraries. +* API calls to Visier's public APIs built on top of a Next.js application. -## Technical Summary -This application is built using [React](https://react.dev/) and [Next.js](https://nextjs.org/). +Baselayer is built with [React](https://react.dev/) and [Next.js](https://nextjs.org/). It consists of 4 smaller React components, each showcasing a Visier API. All React components live together in the main React app. The React components use Visier's [Data Model and Data Query API](https://docs.visier.com/developer/apis/data-model-query/data-model-query-api.htm). Next.js routes API calls through `pages/api/execute.js`, which utilizes `axios` to make API calls. Each API call routes through this workflow before returning the data. Each component sets up its own API call within the component itself. -It is built of 4 smaller React components, each of which showcases a Visier Alpine API. All of these live together as part of the main React app. -- Most of the API explores the capabilities of the [Data Model and Data Query API](https://docs.visier.com/developer/apis/data-model-query/data-model-query-api.htm#:~:text=Use%20the%20Data%20Model%20API,in%20Visier%20unless%20otherwise%20specified.) -- We also have built in a data intake widget to showcase the [Data Intake API](https://docs.visier.com/developer/Tutorials/data-file-upload/upload-data-files-solution.htm). +Baselayer also has a data intake widget to showcase Visier's [Direct Data Intake API](https://docs.visier.com/developer/Tutorials/direct-data-intake/send-data-to-visier.htm). -Next.js routes the API calls through the `pages/api/execute.js` which utilizes `axios` in order to make API calls. Each API call is routed through this workflow before returning the data back. Each component also sets up its own API call within the component itself as well. +To use Baselayer, you must authenticate with OAuth 2.0 in Visier. +# Prerequisites +* Register a client application in Visier. For more information, see [Register a Client Application](https://docs.visier.com/developer/Studio/sign-in%20settings/oauth2-setup.htm). + * Obtain the client application's `Client ID` and `Client secret`. + * Set the client application's `Redirect URI` to http://localhost:3000/oauth2/callback. In development mode, Baselayer listens for authorization codes at this URL. +* Retrieve your Visier API key. For more information, see [Generate an API Key](https://docs.visier.com/developer/Studio/solution%20settings/api-key-generate.htm). +* Create Expense Report objects and load data in Visier. For more information, see [Create a Subject to Analyze Expense Report Data](https://docs.visier.com/developer/Tutorials/analytic-model/extend-analytic-model-subject.htm). +* Install `node`. -## Prerequisites -There are a few pre-requisites before Baselayer will work out of the box. -- You must register a client application in Visier and obtain its `Client ID` and `Client Secret`. -- You must have a Visier `API Key`. -- You must have completed the [Extend the Analytic Model: Create a Subject](https://docs.visier.com/developer/Tutorials/analytic-model/extend-analytic-model-subject.htm) tutorial successfully and set up expense report subjects. -- In development mode, the application will listen for authorization codes on http://localhost:3000/oauth2/callback. The registered client application must also have a redirect URI that exactly matches this application. +# Environment +Before you start the application, create a file named `.env.development.local` to define the following variables: +* `VISIER_HOST`: The base URL for API calls; for example, `https://vanity.api.visier.io`. +* `VISIER_APIKEY`: The API key required for all Visier API calls. +* `VISIER_CLIENT_ID`: A Visier-generated unique identifier for the registered OAuth 2.0 client. +* `VISIER_CLIENT_SECRET`: A Visier-generated secret to protect the registered OAuth 2.0 client. -You must also have `node` installed. +## Installation +Run `yarn install` in a command line application of your choice, such as Terminal. -## Client Environment -The application-specific values are provided to the application through an environment file. -Before starting the application, create a file named `.env.development.local` to provide actual values for the following variables: -```sh -VISIER_HOST=https://customer-specific.api.visier.io -VISIER_CLIENT_ID='client-id-from-registration' -VISIER_CLIENT_SECRET='client-secret-from-registration' -VISIER_APIKEY='visier-provided-api-key' -``` - -## Installation and Running -First install the dependencies by running `yarn install` in your command line application of choice, such as Terminal. Executing `yarn dev` will run the application in development mode. Afterwards, navigate to `localhost:3000` in order to login, authenticate, and begin sending API calls. +## Run the Sample +Execute `yarn dev` to run Baselayer in development mode. Next, navigate to `localhost:3000` to login, authenticate, and begin sending API calls. diff --git a/sample-application/baselayer/pages/api/execute.js b/sample-application/baselayer/pages/api/execute.js index fe7580f..bb51a77 100644 --- a/sample-application/baselayer/pages/api/execute.js +++ b/sample-application/baselayer/pages/api/execute.js @@ -9,7 +9,7 @@ export default async (req, res) => { const data = await POST(req); res.status(200).json(data.data); } catch (error) { - res.status(500).json({ error: error.toString() }); //Make sure your error is serializable or use error.message + res.status(500).json({ error: error.toString() }); // Make sure your error is serializable or use error.message } } else { // Handle any requests that aren't POST diff --git a/sample-application/baselayer/src/app/data-intake/page.js b/sample-application/baselayer/src/app/data-intake/page.js index 6b5be78..648e0ad 100644 --- a/sample-application/baselayer/src/app/data-intake/page.js +++ b/sample-application/baselayer/src/app/data-intake/page.js @@ -84,10 +84,10 @@ export default function DataIntake() { return ( - Data Upload (Data Intake API) + Data Upload (Direct Data Intake API) Load data directly into Visier objects. These objects can be delivered as part of Visier Blueprint, locally modified objects, or even completely custom objects. - Please upload expense report data. + In this application, please upload expense report data.
@@ -114,4 +114,4 @@ export default function DataIntake() { ); -} \ No newline at end of file +} diff --git a/sample-application/baselayer/src/app/data-model/page.js b/sample-application/baselayer/src/app/data-model/page.js index 55a315a..975ca10 100644 --- a/sample-application/baselayer/src/app/data-model/page.js +++ b/sample-application/baselayer/src/app/data-model/page.js @@ -49,9 +49,9 @@ export default function DataModel() { return ( - Expense Reports Dimensions (Data Model API) + Expense Report Dimensions (Data Model API) - The response will return a list of all expense report dimensions. + The response returns a list of all expense report dimensions. @@ -101,4 +101,4 @@ export default function DataModel() { ); -} \ No newline at end of file +} diff --git a/sample-application/baselayer/src/app/data-query-metrics/page.js b/sample-application/baselayer/src/app/data-query-metrics/page.js index 9e85e82..6ccd22c 100644 --- a/sample-application/baselayer/src/app/data-query-metrics/page.js +++ b/sample-application/baselayer/src/app/data-query-metrics/page.js @@ -54,7 +54,7 @@ export default function DataQuery() { const formattedData = { count: count.trim(), - visierTime: visierTime.trim().split(' - ')[0] // Extract the datetime without the ' - [0]' part + visierTime: visierTime.trim().split(' - ')[0] // Extract the datetime without ' - [0]'. }; setExpenseReportsValue(formattedData); @@ -86,7 +86,7 @@ export default function DataQuery() { const formattedData = { count: count.trim(), - visierTime: visierTime.trim().split(' - ')[0] // Extract the datetime without the ' - [0]' part + visierTime: visierTime.trim().split(' - ')[0] // Extract the datetime without ' - [0]'. }; setExpenseReportsCount(formattedData); @@ -125,7 +125,7 @@ export default function DataQuery() { {expenseReportsValue?.count} - Avg Value of Expense Report + Average Value of Expense Report {expenseReportsValue?.count / expenseReportsCount?.count} @@ -134,4 +134,4 @@ export default function DataQuery() { ); -} \ No newline at end of file +} diff --git a/sample-application/baselayer/src/app/layout.js b/sample-application/baselayer/src/app/layout.js index e25c955..85b62a3 100644 --- a/sample-application/baselayer/src/app/layout.js +++ b/sample-application/baselayer/src/app/layout.js @@ -18,8 +18,8 @@ import React from 'react'; const inter = Inter({ subsets: ['latin'] }) export const metadata = { - title: 'Visier Sample app', - description: 'Public Visier sample application with OAuth and API calls', + title: 'Visier Sample Application', + description: 'Public Visier sample application with OAuth 2.0 and API calls', } export default function RootLayout({ children }) { @@ -31,4 +31,4 @@ export default function RootLayout({ children }) { ) } - \ No newline at end of file + diff --git a/sample-application/baselayer/src/app/page.js b/sample-application/baselayer/src/app/page.js index 17716be..7d5e622 100644 --- a/sample-application/baselayer/src/app/page.js +++ b/sample-application/baselayer/src/app/page.js @@ -39,21 +39,22 @@ export default function Home() { -

Expense Report Baselayer Application

-

A Sample Application built on Alpine by Visier

+

Visier Baselayer Application

+

A sample application built on Alpine by Visier

- This is a sample Next.js application that shows calls to our Data Model, Data Query and Data Intake APIs. It utilizes our OAuth-API flow for authentication. - Please consult the README.md file for how to configure the Visier access using OAuth 2.0. + This is a sample Next.js application that shows calls to Visier's Data Model, Data Query, and Direct Data Intake APIs. It utilizes Visier's OAuth 2.0 authentication flow. + For more information about configuring Visier access with OAuth 2.0, see the README.md.

-

Pre-requisites and Resources

+

Prerequisites

- There are some pre-requisites you need to do before you can get this application API calls working: + Before calling this application's APIs, you need:

@@ -79,13 +80,13 @@ export default function Home() { <> - Visier Application Baselayer + Visier Baselayer Application - This is a sample Next.js application that shows the three-legged (authorization_code flow) OAuth authentication with calls to our Data Model, Data Query and Data Intake APIs. - Please consult the README.md file for how to configure the Visier access using OAuth 2.0. + This is a sample Next.js application that shows the three-legged (`authorization_code` grant type) OAuth authentication with calls to Visier's Data Model, Data Query, and Direct Data Intake APIs. + For more information about configuring Visier access with OAuth 2.0, see the README.md. - Note: This is a sample application intended to showcase Visier Alpine APIs and Oauth functionality. For information about acceptable use, see the LICENSE file. + Note: This sample application shows Visier's public APIs and OAuth 2.0 functionality. For information about acceptable use, see the LICENSE file.