mirror of
https://github.com/LukeHagar/developer.sailpoint.com.git
synced 2025-12-09 12:27:47 +00:00
added docs for the rest of the app dev process
This commit is contained in:
Philip Ellis
File diff suppressed because it is too large
Load Diff
45
docs/tools/ui-development-kit/deploying.md
Normal file
45
docs/tools/ui-development-kit/deploying.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
id: udk-deploying
|
||||
title: Deploying
|
||||
pagination_label: UDK
|
||||
sidebar_label: Deploying
|
||||
sidebar_position: 2
|
||||
sidebar_class_name: rudk
|
||||
keywords: ['UI', 'development', 'kit']
|
||||
description: Deploying your UI project
|
||||
slug: /tools/ui-development-kit/deploying
|
||||
tags: ['UI']
|
||||
---
|
||||
|
||||
## Building the App
|
||||
|
||||
To build the app locally, you can simply run the command `npm run electron:build` and the app will be built for your platform. The location of the built file can be found in the `./release` folder.
|
||||
|
||||
### Building for different platforms
|
||||
|
||||
If you want to build a release that can be used on other platforms, then you can use the github workflows to accomplish this task. By forking the repository, you will also have access to the github actions in the .github/workflows directory and there is an action for macos, linux and windows that can be used to build the application. Upon a successful build, the built executable is stored in github as a resource.
|
||||
|
||||
### Building with customization
|
||||
|
||||
Inside the `app/config.json` are the default navigation menu items that will presented to a user when they run the app. You can modify these values so that the bundled application will only allow the user to access certain pre-built components. That way if you want to bundle a purpose built app that only has access to the transform builder, you can do that by modifying the `app/config.json` like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"components": {
|
||||
"enabled": [
|
||||
"transforms"
|
||||
]
|
||||
},
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
In this case the user won't even have access to the component selector to enable other components, so the app will be limited to only the transform tool. You can also adjust the custom themes for the app using the `config.json` as well, to see more on this, see [theming](./theming)
|
||||
|
||||
Once the app is started, the user settings will be stored in the users `appData/Roaming/sailpoint-ui-development-kit` folder and can be modified there to allow access to other components if desired.
|
||||
|
||||
:::info
|
||||
|
||||
The UI Development Kit uses the existing configuration stored in the users data directory. If there is a pre-installed instance of the app or the config.json file already exists, it will not be overwritten by the application and their current configuration will be used.
|
||||
|
||||
:::
|
||||
@@ -11,128 +11,54 @@ slug: /tools/ui-development-kit/error-handling
|
||||
tags: ['UI', 'Error']
|
||||
---
|
||||
|
||||
Ideally, everything in your custom UIs will work smoothly, but you will likely encounter errors at some point when you're implementing a page. If you provide an invalid filter or sorter, the list accounts endpoint will return a 400 error, for example. You can handle this error by adding a `try catch` block to the server side of the accounts list page.
|
||||
Ideally, everything in your custom UIs will work smoothly, but you will likely encounter errors at some point when you're implementing a page. For example, if you provide an invalid filter or sorter, the list accounts endpoint will return a 400 error. Even though the actual calls happen in the backend electron code, you almost never need to interact with that part of the application. Instead, it is best to handle all the errors on the front end
|
||||
|
||||
If any of your backend calls result in a server error or bad request, you also want to handle those errors.
|
||||
|
||||
Read this guide to learn how to use the UI Development Kit to handle errors.
|
||||
|
||||
## 400 bad request
|
||||
## Handling errors in your code
|
||||
|
||||
If you provide an invalid filter or sorter, the [List Accounts Endpoint](https://developer.sailpoint.com/docs/api/v3/list-accounts) returns a 400 error. This example awaits the response and doesn't exit the program when a 4xx level status is received. If a 4xx level status is received, the user is redirected to an error page.
|
||||
If you provide an invalid filter or sorter, the [List Accounts Endpoint](https://developer.sailpoint.com/docs/api/v2025/list-accounts) returns a 400 error. This example uses a try/catch to handle the error and present the user with what went wrong.
|
||||
|
||||
Refer to this code block to learn how to implement error handling for invalid filters or sorters:
|
||||
This is just one example of how things can be handled during an error event. Sometimes it can be better to present the user with a popup, or you can use a snackbar to show a quick popup on the bottom of the page.
|
||||
|
||||
```typescript
|
||||
import {createConfiguration} from '$lib/sailpoint/sdk.js';
|
||||
import {getFilters, getLimit, getPage, getSorters} from '$lib/Utils.js';
|
||||
import {error} from '@sveltejs/kit';
|
||||
import {AccountsApi} from 'sailpoint-api-client';
|
||||
|
||||
export const load = async ({url, locals}) => {
|
||||
const config = createConfiguration(
|
||||
locals.session!.baseUrl,
|
||||
locals.idnSession!.access_token,
|
||||
);
|
||||
const api = new AccountsApi(config);
|
||||
// initially, set error to false and have no error message
|
||||
this.error = false;
|
||||
this.errorMessage = '';
|
||||
|
||||
const page = getPage(url);
|
||||
const limit = getLimit(url);
|
||||
const sorters = getSorters(url);
|
||||
const filters = getFilters(url);
|
||||
|
||||
const reportResp = await api.listAccounts(
|
||||
{
|
||||
count: true,
|
||||
sorters: sorters,
|
||||
filters: filters,
|
||||
limit: Number(limit),
|
||||
offset: Number(page) * Number(limit),
|
||||
},
|
||||
{
|
||||
validateStatus: function (status) {
|
||||
return status < 500;
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
if (reportResp.status !== 200) {
|
||||
error(400, {
|
||||
message:
|
||||
'an error occurred while fetching accounts. Please examine your filters and and sorters and try again.',
|
||||
context: {params: {page, limit, filters, sorters}},
|
||||
urls: [
|
||||
'https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results',
|
||||
],
|
||||
errData: reportResp.data,
|
||||
});
|
||||
}
|
||||
|
||||
const totalCount = reportResp.headers['x-total-count'];
|
||||
const accountData = reportResp.data;
|
||||
|
||||
return {accountData, totalCount, params: {page, limit, sorters, filters}};
|
||||
};
|
||||
try {
|
||||
const response = await this.sdk.listAccounts(request);
|
||||
if (response.status !== 200) { // check to see if the response code is the expected value. In case it's not, just throw an error as it will be handled in the try catch block
|
||||
throw new Error(`Failed to load accounts: ${response.statusText}`);
|
||||
}
|
||||
this.accounts = response.data;
|
||||
} catch (error) { // In case the SDK encounters some error in the request
|
||||
console.error('Error loading accounts:', error);
|
||||
this.error = true;
|
||||
this.errorMessage = error instanceof Error ? error.message : String(error);
|
||||
this.accounts = [];
|
||||
} finally {
|
||||
this.loading = false;
|
||||
}
|
||||
```
|
||||
|
||||
## 500 server issues
|
||||
Present the user with the error message if there is an error present during loading any data
|
||||
```html
|
||||
<div *ngIf="error" class="error-message mat-elevation-z1">
|
||||
<mat-icon color="warn">error</mat-icon>
|
||||
<span>Error loading accounts: {{ errorMessage }}</span>
|
||||
</div>
|
||||
```
|
||||
|
||||
You can update the code block to handle more than just the 400 level statuses. You can see the highlighted code changes to handle any error response from the API call. You can send back an error to the user with the status, a detailed message, the details about the parameters used that caused the error, and the error response from the API.
|
||||
## Retrieving logs from the app
|
||||
|
||||
Refer to this code block to learn how to implement error handling for other non-400 errors:
|
||||
When running the built app locally, you can retrieve details logging from the app by running the executable with the `--enable-logging` flag enabled. For example:
|
||||
|
||||
```typescript
|
||||
import {createConfiguration} from '$lib/sailpoint/sdk.js';
|
||||
import {getFilters, getLimit, getPage, getSorters} from '$lib/Utils.js';
|
||||
import {error} from '@sveltejs/kit';
|
||||
import {AccountsApi} from 'sailpoint-api-client';
|
||||
|
||||
export const load = async ({url, locals}) => {
|
||||
const config = createConfiguration(
|
||||
locals.session!.baseUrl,
|
||||
locals.idnSession!.access_token,
|
||||
);
|
||||
const api = new AccountsApi(config);
|
||||
|
||||
const page = getPage(url);
|
||||
const limit = getLimit(url);
|
||||
const sorters = getSorters(url);
|
||||
const filters = getFilters(url);
|
||||
|
||||
const reportResp = await api.listAccounts(
|
||||
{
|
||||
count: true,
|
||||
sorters: sorters,
|
||||
filters: filters,
|
||||
limit: Number(limit),
|
||||
offset: Number(page) * Number(limit),
|
||||
},
|
||||
{
|
||||
validateStatus: function (status) {
|
||||
// highlight-next-line
|
||||
return status < 550;
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
if (reportResp.status !== 200) {
|
||||
// highlight-next-line
|
||||
error(reportResp.status, {
|
||||
message:
|
||||
'an error occurred while fetching accounts. Please examine your filters and and sorters and try again.',
|
||||
context: {params: {page, limit, filters, sorters}},
|
||||
urls: [
|
||||
'https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results',
|
||||
],
|
||||
errData: reportResp.data,
|
||||
});
|
||||
}
|
||||
|
||||
const totalCount = reportResp.headers['x-total-count'];
|
||||
const accountData = reportResp.data;
|
||||
|
||||
return {accountData, totalCount, params: {page, limit, sorters, filters}};
|
||||
};
|
||||
```powershell
|
||||
& '.\sailpoint-ui-development-kit 1.0.0.exe' --enable-logging
|
||||
```
|
||||
|
||||
## Discuss
|
||||
|
||||
BIN
docs/tools/ui-development-kit/img/theme-component.png
Normal file
BIN
docs/tools/ui-development-kit/img/theme-component.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
@@ -46,7 +46,7 @@ The first step to setting up the UI Development Kit is to clone the project from
|
||||
To clone the project, you can run this command:
|
||||
|
||||
```bash
|
||||
git clone git@github.com:sailpoint-oss/ui-development-kit.git
|
||||
git clone https://github.com/sailpoint-oss/ui-development-kit.git
|
||||
```
|
||||
|
||||
## Project structure
|
||||
|
||||
@@ -11,4 +11,12 @@ slug: /tools/ui-development-kit/theming
|
||||
tags: ['UI']
|
||||
---
|
||||
|
||||
Read this guide to learn about the UI Development Kit and how to use it. Once you have read this guide, you will be able to do the following:
|
||||
If you want to create a custom theme for your deployment, you can do it easily using the config file and the theme config component:
|
||||
|
||||
## Using the theme component
|
||||
|
||||
Using the theme component, you can select colors for all the main objects on the UI such as the primary and secondary colors, as well as pick which logos will appear for dark and light mode. Once you have these changes made, the settings will be saved in your `appData/Roaming/sailpoint-ui-development-kit` and the app can be deployed with these settings deployed along with the app by using the [deployment guide](./deploying.)
|
||||
|
||||
## Example Theme Component
|
||||
|
||||
|
||||
Reference in New Issue
Block a user