### Clone SkillTree Examples and Start Live Server

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This sequence of commands clones the `skills-client-examples` repository, navigates into the JavaScript example directory, installs dependencies, and starts the live-server development server. Node.js and npm are required.

```bash
git clone git@github.com:NationalSecurityAgency/skills-client-examples.git
cd skills-client-examples/js-example
npm install
npm run serve
```

--------------------------------

### Initialize JavaScript Project and Install Live Server

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

These commands set up a new JavaScript project directory, initialize it with npm, and install `live-server` as a development dependency. This is part of the manual setup for the client integration example.

```bash
mkdir js-example
cd js-example
npm init
# accept defaults
npm install --save-dev live-server
```

--------------------------------

### Start Java Backend Example

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This command starts the `java-backend-example` application using a downloaded JAR file. Replace 'X.X.X' with the actual version number of the downloaded JAR. This application populates the skills-service with sample data.

```bash
java -jar java-backend-example-X.X.X.jar
```

--------------------------------

### Download Java Backend Example using Curl

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This command downloads the latest Java backend example release from GitHub. It uses `curl` to fetch release information, `grep` to find the download URL, `cut` to extract it, and `wget` to download the file. Ensure `wget` is installed.

```bash
curl -s https://api.github.com/repos/NationalSecurityAgency/skills-client-examples/releases/latest | grep browser_download_url | cut -d '"' -f 4 | wget -qi -
```

--------------------------------

### Start Live Server for SkillTree JS Example

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This command starts the `live-server` development server with specific configurations for the SkillTree JavaScript example. It disables the browser from opening automatically, sets the port, enables CORS, and proxies API requests to the `skills-service` and the server itself.

```bash
npx live-server --no-browser --port=8092 --open=app --cors --proxy=/api:http://localhost:8090/api --proxy=/native:http://localhost:8092/
```

--------------------------------

### Start PostgreSQL using Docker

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This command starts a PostgreSQL database in a Docker container. It maps the container's port to the host and sets up basic user credentials. This is useful if a local PostgreSQL instance is not already available.

```shell
docker run --network=host -e POSTGRES_USER=skills -e POSTGRES_PASSWORD=skillsPassword -d postgres
```

--------------------------------

### Install SkillTree JS Client Library

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This command installs the SkillTree JavaScript client library using npm. It adds the library as a dependency to your project, allowing you to integrate SkillTree features into your web application.

```bash
npm install @skilltree/skills-client-js --save
```

--------------------------------

### Install Dependencies and Run Cypress Tests

Source: https://skilltreeplatform.dev/contribution/devEnv

These commands install the necessary Node.js dependencies for the end-to-end tests and then execute the Cypress integration tests. It also includes commands to start and stop the required services in the background.

```bash
cd skills-service/e2e-tests
npm install

# start servers in the background: skills-service and client-display
npm run cyServices:start
# run cypress integration tests
npm run cy:run
# kill background servers
npm run cyServices:kill
```

--------------------------------

### Start SkillTree Service with Docker

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This command deploys the SkillTree skills-service using a Docker image. It configures the service to connect to a PostgreSQL database running on localhost and exposes the service on port 8080. Remember to replace <tag_version> with the desired version.

```shell
docker run --name skills-service -d -p 8080:8080 -e SPRING_PROPS="\nspring.datasource.url=jdbc:postgresql://localhost:5432/skills,\nspring.datasource.username=skills,\nspring.datasource.password=skillsPassword" skilltree/skills-service:<tag_version>
```

--------------------------------

### Execute Cypress Integration Tests (npm)

Source: https://skilltreeplatform.dev/contribution/devEnv

This sequence of commands installs dependencies, starts necessary services, runs Cypress integration tests, and then stops the services. It's used for end-to-end testing of the SkillTree application.

```bash
cd skills-service/e2e-tests
npm install

# start servers in the background: skills-service and client-display to test
npm run cyServices:start
# run cypress integration tests
npm run cy:run
# kill background servers
npm run cyServices:kill
```

--------------------------------

### Configure SkillTree Client Library

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This JavaScript code configures the SkillTree client library for your application. It sets the `serviceUrl`, `projectId`, and `authenticator`. This configuration should be done once per user session. Ensure the service URLs are correct for your environment.

```javascript
SkillsConfiguration.configure({
    serviceUrl: 'http://localhost:8080',
    projectId: 'movies',
    authenticator: 'http://localhost:8090/api/users/user4@email.com/token',
});
```

--------------------------------

### Run SkillTree Service with JAR

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This command executes the downloaded SkillTree skills-service JAR file. It configures the service to connect to a PostgreSQL database on localhost using specific credentials and system properties. Substitute `X.X.X` with the actual version of the downloaded JAR.

```shell
java -Dspring.datasource.url=jdbc:postgresql://localhost:5432/skills \
-Dspring.datasource.username=skills \
-Dspring.datasource.password=skillsPassword \
-jar ~/Downloads/skills-service-X.X.X.jar
```

--------------------------------

### Start Vite Development Server for Dashboard

Source: https://skilltreeplatform.dev/contribution/devEnv

This command starts the Vite development server for the web-based dashboard. It runs on port 5173 and communicates with the skills-service running on port 8080.

```bash
cd dashboard
npm run dev
```

--------------------------------

### Download Latest SkillTree JAR Release

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This command uses `curl` and `wget` to download the latest release of the SkillTree skills-service JAR file from GitHub. It queries the GitHub API to find the direct download URL for the latest release.

```shell
curl -s https://api.github.com/repos/NationalSecurityAgency/skills-service/releases/latest | grep browser_download_url | cut -d '"' -f 4 | wget -qi -
```

--------------------------------

### Tail SkillTree Service Docker Logs

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This command allows you to monitor the logs of a running SkillTree services Docker container in real-time. Replace <container_id> with the actual ID of your running container.

```shell
docker logs -f <container_id>
```

--------------------------------

### Configure Docker-based Install with Application and System Properties

Source: https://skilltreeplatform.dev/dashboard/install-guide/config

This example demonstrates configuring both application and system properties for the Docker-based installation of the skills-service. `SPRING_PROPS` is used for application properties and `EXTRA_JAVA_OPTS` for system properties.

```bash
docker run --name skills-service -d -p 8080:8080 \
-e SPRING_PROPS="\
spring.datasource.url=jdbc:postgresql://<host>:5432/skills,\
spring.datasource.username=<username>,\
spring.datasource.password=<password>" \
-e EXTRA_JAVA_OPTS="-Xmx2G -Xms2G" \
skilltree/skills-service:<version>
```

--------------------------------

### Import SkillTree JS Client Library using Script Tag

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This HTML script tag demonstrates how to import the SkillTree JavaScript client library using ES Modules from a CDN. It makes `SkillsConfiguration`, `SkillsDisplayJS`, and `SkillsReporter` available for use in your application.

```html
<script type="module">
    import {
        SkillsConfiguration,
        SkillsDisplayJS,
        SkillsReporter
    } from 'https://unpkg.com/@skilltree/skills-client-js/dist/skills-client-js.esm.min.js'

// Use imported components
// ...
</script>
```

--------------------------------

### Configure Jar-based Install with JVM System Properties

Source: https://skilltreeplatform.dev/dashboard/install-guide/config

This example shows how to configure the Jar-based installation of the skills-service using JVM system properties. Properties are passed before the JAR file, prefixed with `-D` or `-X`.

```bash
java -Xmx2G -Xms2G -jar ~/Downloads/skills-service-X.X.X.jar
```

--------------------------------

### WebVTT Example for Captions

Source: https://skilltreeplatform.dev/dashboard/user-guide/skills

An example demonstrating the WebVTT format for video captions. This format allows for synchronized text tracks to be displayed with video playback, and SkillTree provides a button to prefill an example in the captions input form.

```webvtt
WEBVTT

1
00:00:01.000 --> 00:00:05.000
This is the first caption.

2
00:00:06.000 --> 00:00:10.000
This is the second caption.
```

--------------------------------

### Clone SkillTree Repository

Source: https://skilltreeplatform.dev/contribution/devEnv

This command clones the skills-service repository from GitHub. This is the first step in setting up the project locally to begin development.

```bash
git clone <github>:skills-service.git
```

--------------------------------

### Initialize and Attach SkillTree JS Display

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This JavaScript code initializes the `SkillsDisplayJS` component and attaches it to a specified DOM element. This component is responsible for visualizing user skills and rankings within your application. The `version` parameter can be adjusted as needed.

```javascript
const clientDisplay = new SkillsDisplayJS({version: 1});
clientDisplay.attachTo(document.querySelector('#skills-client-container'));
```

--------------------------------

### Configure SkillTree Reporter Success Handler

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This JavaScript code configures the `SkillsReporter` to notify when a skill is not applied and sets up a success handler to display the results of skill reporting. The results are stringified and displayed in a designated HTML element.

```javascript
// just so we can always see the response
SkillsReporter.configure({notifyIfSkillNotApplied: true});
SkillsReporter.addSuccessHandler((result) => {
    document.querySelector('#reportResultContainer').innerHTML = JSON.stringify(result, null, ' ');
});
```

--------------------------------

### Report Skill Events with SkillTree JS

Source: https://skilltreeplatform.dev/dashboard/install-guide/quickStart

This JavaScript code sets up an event listener for a button click. When clicked, it calls `SkillsReporter.reportSkill` to report the completion of a specific skill, identified by its name (e.g., 'IronMan').

```javascript
document.querySelector('#reportSkillButton').onclick = function () {
    SkillsReporter.reportSkill('IronMan');
};
```

--------------------------------

### Theme Configuration Object Example

Source: https://skilltreeplatform.dev/skills-client/legacy

An example of a theme configuration object, specifically a 'Dark Blue' theme, showcasing various customizable color properties for different UI elements like backgrounds, text, stars, progress indicators, charts, tiles, buttons, and prerequisites.

```javascript
{
      maxWidth: '100%',
      backgroundColor: '#626d7d',
      landingPageTitle: 'Themed User Skills',
      pageTitle: {
        textColor: 'white',
        fontSize: '1.5rem',
      },
      textSecondaryColor: 'white',
      textPrimaryColor: 'white',
      stars: {
        unearnedColor: '#787886',
        earnedColor: 'gold',
      },
      progressIndicators: {
        beforeTodayColor: '#3e4d44',
        earnedTodayColor: '#667da4',
        completeColor: '#59ad52',
        incompleteColor: '#cdcdcd',
      },
      charts: {
        axisLabelColor: 'white',
      },
      tiles: {
        backgroundColor:'#152E4d',
        watermarkIconColor: '#a6c5f7',
      },
      buttons: {
        backgroundColor: '#152E4d',
        foregroundColor: '#59ad52',
      },
      prerequisites: {
        achievedColor: '#6df28b',
        skillColor: '#ffe297',
        badgeColor: '#ceb6f4',
        thisSkillColor: '#7fbbfa',
        navButtonsColor: '#cce7f3',
      },
    }

```

--------------------------------

### Install Skilltree React Client Library

Source: https://skilltreeplatform.dev/skills-client/legacy

This command installs the Skilltree client library for React applications using npm. This library provides utilities for Skills Configuration, Skills Display, and Skill Event Reporting.

```bash
npm install @skilltree/skills-client-react --save
```

--------------------------------

### Build and Test SkillTree Service (Maven)

Source: https://skilltreeplatform.dev/contribution/devEnv

This command navigates into the skills-service directory and then builds the project using Maven, running all unit and backend integration tests. This process can take 5 to 20 minutes.

```bash
cd skills-service
mvn install
```

--------------------------------

### Configure Docker-based Install with Application Properties

Source: https://skilltreeplatform.dev/dashboard/install-guide/config

This example illustrates configuring the Docker-based installation of the skills-service using environment variables for application properties. The `SPRING_PROPS` environment variable is used, with properties separated by commas.

```bash
docker run --name skills-service -d -p 8080:8080 \
-e SPRING_PROPS="\
spring.datasource.url=jdbc:postgresql://<host>:5432/skills,\
spring.datasource.username=<username>,\
spring.datasource.password=<password>" \
skilltree/skills-service:<version>
```

--------------------------------

### SkillsDisplay Options Object Example (JavaScript)

Source: https://skilltreeplatform.dev/skills-client/legacy

Provides an example of how to configure the SkillsDisplay component using the `options` object. This object controls various behaviors like scrolling and display modes.

```javascript
{
    disableAutoScroll: false,
    autoScrollStrategy: 'top-of-page',
}

```

--------------------------------

### Run SkillTree Dashboard and Service (Java)

Source: https://skilltreeplatform.dev/contribution/devEnv

This command executes the built SkillTree runtime artifact (a Spring Boot application) using Java. The application will be accessible at http://localhost:8080.

```bash
java -jar service/target/skills-service-<version>.jar
```

--------------------------------

### Theme Object Configuration Example

Source: https://skilltreeplatform.dev/skills-client/js

An example of a 'Dark Blue' theme object used for customizing the visual appearance of various UI elements within the skilltree platform. This object includes settings for background and foreground colors, text styles, and specific component colors for badges and prerequisites.

```javascript
{
  maxWidth: '100%',
  backgroundColor: '#626d7d',
  landingPageTitle: 'Themed User Skills',
  pageTitle: {
    textColor: 'white',
    fontSize: '1.5rem',
  },
  textSecondaryColor: 'white',
  textPrimaryColor: 'white',
  stars: {
    unearnedColor: '#787886',
    earnedColor: 'gold',
  },
  progressIndicators: {
    beforeTodayColor: '#3e4d44',
    earnedTodayColor: '#667da4',
    completeColor: '#59ad52',
    incompleteColor: '#cdcdcd',
  },
  charts: {
    axisLabelColor: 'white',
  },
  tiles: {
    backgroundColor:'#152E4d',
    watermarkIconColor: '#a6c5f7',
  },
  buttons: {
    backgroundColor: '#152E4d',
    foregroundColor: '#59ad52',
  },
  prerequisites: {
    achievedColor: '#6df28b',
    skillColor: '#ffe297',
    badgeColor: '#ceb6f4',
    thisSkillColor: '#7fbbfa',
    navButtonsColor: '#cce7f3',
  },
}
```

--------------------------------

### Install Angular Client Library for Skilltree

Source: https://skilltreeplatform.dev/skills-client/legacy

Installs the Angular client library for Skilltree using npm. This library includes utilities for Skills Configuration, Skills Display, and Skill Event Reporting.

```bash
npm install @skilltree/skills-client-ng --save

```

--------------------------------

### Skills Display Options Object Example

Source: https://skilltreeplatform.dev/skills-client/js

An example of how to configure the Options object for the Skills Client Display. This object allows for customization of scrolling behavior and other display features.

```javascript
{
    disableAutoScroll: false,
    autoScrollStrategy: 'top-of-page'
}
```

--------------------------------

### Configure Database Connection for Skills Service

Source: https://skilltreeplatform.dev/contribution/devEnv

These properties configure the database connection for the skills-service. Ensure you replace `<username>` and `<password>` with your actual database credentials.

```properties
spring.datasource.url=jdbc:postgresql://localhost:5432/skillsspring.datasource.username=<username>spring.datasource.password=<password>
```

--------------------------------

### Configure Database Connection for SkillTree

Source: https://skilltreeplatform.dev/dashboard/install-guide/prodInstall

These properties define the connection details for the PostgreSQL database, which is required for a production-grade SkillTree installation. Ensure the username and password are set correctly.

```properties
spring.datasource.url=jdbc:postgresql://<server>:5432/skills
spring.datasource.username=
spring.datasource.password=
```

--------------------------------

### Run skills-service via Jar with PostgreSQL

Source: https://skilltreeplatform.dev/dashboard/install-guide/devInstall

This command executes the SkillTree skills-service from a downloaded JAR file. It requires a PostgreSQL database and expects the connection details to be passed as command-line arguments. Replace 'X.X.X' with the actual version of the JAR file.

```bash
java -jar ~/Downloads/skills-service-X.X.X.jar \
--spring.datasource.url=jdbc:postgresql://<host>:5432/skills \
--spring.datasource.username=<username> \
--spring.datasource.password=<pass>
```

--------------------------------

### Run Service Tests with PostgreSQL (Maven)

Source: https://skilltreeplatform.dev/contribution/devEnv

This command executes service tests using Maven, overriding default properties to connect to a PostgreSQL database. Replace placeholders with actual credentials.

```bash
mvn --batch-mode test -Dspring.datasource.url=jdbc:postgresql:postgres:5432/skills -Dspring.datasource.username=user -Dspring.datasource.password=pass
```

--------------------------------

### Example SkillsReporter Response Object

Source: https://skilltreeplatform.dev/skills-client/js

An example of a typical response object received after successfully reporting a skill event using the SkillsReporter. This object provides information about the success of the operation, whether the skill was applied, and an explanation.

```json
{
  "success": true,
  "skillApplied": true,
  "explanation": "Skill event was applied",
  "completed": []
}
```

--------------------------------

### Open Cypress for Development Tests

Source: https://skilltreeplatform.dev/contribution/devEnv

This command opens the Cypress test runner in development mode, allowing you to write and execute end-to-end tests for the dashboard application.

```bash
cd e2e-tests
npm run cy:open:dev
```

--------------------------------

### Run Maven Tests for Skills Service

Source: https://skilltreeplatform.dev/contribution/devEnv

This command navigates to the skills-service project directory and executes all service tests using Maven. It's essential for verifying the integrity of the programmatic REST API.

```bash
cd skills-service/service
mvn test
```

--------------------------------

### Install SkillsReporter Vue.js Client Library

Source: https://skilltreeplatform.dev/skills-client/legacy

Command to install the SkillsReporter client library for Vue.js projects using npm. This library provides components and utilities for integrating Skilltree features into a Vue application.

```bash
npm install @skilltree/skills-client-vue --save

```

--------------------------------

### User Info Service Configuration

Source: https://skilltreeplatform.dev/dashboard/install-guide/installModes

Configure the SkillTree service to communicate with your organization's User Info Service for PKI authentication.

```APIDOC
## User Info Service Configuration

### Description
Configures the SkillTree service to interact with a custom User Info Service. This service is crucial for PKI authentication, as it maps user Distinguished Names (DNs) to user metadata like name and email.

### Method
N/A (Configuration Properties)

### Endpoint
N/A

### Parameters
#### Request Body
- **skills.authorization.userInfoUri** (string) - Required - The URI for the User Info Service endpoint that retrieves user information by DN. Example: `https://<host>:<port>/userInfo?dn={dn}`.
- **skills.authorization.userQueryUri** (string) - Required - The URI for the User Info Service endpoint used for querying users, typically for dropdown suggestions. Example: `https://<host>:<port>/userQuery?query={query}`.
- **skills.authorization.userInfoHealthCheckUri** (string) - Optional - The URI for the User Info Service health check endpoint. Example: `https://<host>:<port>/actuator/health`.

### Request Example
```properties
skills.authorization.userInfoUri=https://user-info-service.your-domain.com/userInfo?dn={dn}
skills.authorization.userQueryUri=https://user-info-service.your-domain.com/userQuery?query={query}
skills.authorization.userInfoHealthCheckUri=https://user-info-service.your-domain.com/actuator/health
```

### Response
N/A (Configuration properties do not have direct request/response)

### Notes
Your User Info Service must implement the specified REST endpoints and return JSON responses conforming to the schema described in the documentation for `skills.authorization.userInfoUri` and `skills.authorization.userQueryUri`.
```

--------------------------------

### Configure PostgreSQL Datasource Properties

Source: https://skilltreeplatform.dev/contribution/devEnv

These properties are used to configure the SkillTree application to connect to a PostgreSQL database. Replace <username> and <password> with your actual database credentials.

```properties
spring.datasource.url=jdbc:postgresql://localhost:5432/skills
spring.datasource.username=<username>
spring.datasource.password=<password>
```

--------------------------------

### Run skills-service via Docker with PostgreSQL

Source: https://skilltreeplatform.dev/dashboard/install-guide/devInstall

This command launches the SkillTree skills-service using Docker. It requires a PostgreSQL database to be accessible and configured via environment variables. The command maps port 8080 and expects the database connection details (URL, username, password) to be provided.

```bash
docker run --name skills-service -d -p 8080:8080 \
-e SPRING_PROPS \"\
spring.datasource.url=jdbc:postgresql://<host>:5432/skills,\
spring.datasource.username=<username>,\
spring.datasource.password=<password>\" \
skilltree/skills-service:<version>
```

--------------------------------

### User Info Service Endpoints

Source: https://skilltreeplatform.dev/dashboard/install-guide/installModes

Defines the required REST endpoints for the User Info Service that SkillTree will interact with.

```APIDOC
## User Info Service Endpoints

### Description
Details the contract for the User Info Service, specifying the expected request parameters and response formats for key endpoints.

### Method
GET

### Endpoint
- `/userInfo?dn={dn}` (Configured via `skills.authorization.userInfoUri`)
- `/userQuery?query={query}` (Configured via `skills.authorization.userQueryUri`)
- `/actuator/health` (Configured via `skills.authorization.userInfoHealthCheckUri`)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
- **dn** (string) - Required (for `/userInfo`) - The Distinguished Name (DN) of the user to retrieve information for.
- **query** (string) - Required (for `/userQuery`) - The search query string for user suggestions.

#### Request Body
N/A

### Request Example
- **User Info Request:**
  `GET /userInfo?dn=CN=John Doe,OU=Users,DC=example,DC=com`
- **User Query Request:**
  `GET /userQuery?query=John Doe`

### Response
#### Success Response (200) - `/userInfo` endpoint
- **firstName** (string) - The user's first name.
- **lastFirstName** (string) - The user's last name.
- **email** (string) - The user's email address.
- **username** (string) - A unique identifier for the user (e.g., `000001`).
- **userDn** (string) - The user's Distinguished Name (DN).
- **usernameForDisplay** (string) - The username as it should be displayed in the SkillTree dashboard.

#### Response Example - `/userInfo` endpoint
```json
{
    "firstName": "John",
    "lastFirstName": "Doe",
    "email": "john.doe@example.com",
    "username": "000001",
    "userDn": "CN=John Doe,OU=Users,DC=example,DC=com",
    "usernameForDisplay": "John Doe"
}
```

#### Success Response (200) - `/userQuery` endpoint
A JSON array containing user objects matching the query criteria. Each object follows the same structure as the `/userInfo` response.

#### Response Example - `/userQuery` endpoint
```json
[
    {
        "firstName": "John",
        "lastFirstName": "Doe",
        "email": "john.doe@example.com",
        "username": "000001",
        "userDn": "CN=John Doe,OU=Users,DC=example,DC=com",
        "usernameForDisplay": "John Doe"
    },
    {
        "firstName": "Johnny",
        "lastFirstName": "Doette",
        "email": "j.doette@example.com",
        "username": "000002",
        "userDn": "CN=Johnny Doette,OU=Users,DC=example,DC=com",
        "usernameForDisplay": "Johnny Doette"
    }
]
```

#### Success Response (200) - `/actuator/health` endpoint
Typically returns a health status indicator (e.g., JSON indicating "UP" or "DOWN"). The exact format depends on the Spring Boot Actuator configuration.

#### Response Example - `/actuator/health` endpoint
```json
{
    "status": "UP"
}
```
```

--------------------------------

### skills-service WebSocket Stomp Configuration

Source: https://skilltreeplatform.dev/dashboard/install-guide/prodInstall

Enables and configures the WebSocket Stomp broker relay for real-time communication within the skills-service. Requires the relay host and port to be specified. This is crucial for features relying on live updates.

```properties
skills.websocket.enableStompBrokerRelay=trueskills.websocket.relayHost=skills.websocket.relayPort=
```

--------------------------------

### PKI Authentication Mode

Source: https://skilltreeplatform.dev/dashboard/install-guide/installModes

Configure SkillTree to use PKI (Public Key Infrastructure) for authentication, suitable for intranets with two-way SSL certificates.

```APIDOC
## PKI Auth Mode Configuration

### Description
Enables PKI-based authentication where users authenticate using personal PKI certificates. This mode requires the user's browser to have a valid certificate issued by a trusted Certificate Authority.

### Method
N/A (Configuration Properties)

### Endpoint
N/A

### Parameters
#### Request Body
- **skills.authorization.authMode** (string) - Required - Set to `PKI` to enable PKI authentication mode.

### Requirements
- A running `User Info Service`.
- Client properties configured to communicate with the `User Info Service`.

### Request Example
```properties
skills.authorization.authMode=PKI
```

### Response
N/A (Configuration properties do not have direct request/response)

### Notes
To disable username/password authentication entirely and only support OAuth or PKI based authentication, set `skills.authorization.oAuthOnly=true` (if only OAuth is desired) or ensure PKI is correctly configured for a mixed or PKI-only environment.
```

--------------------------------

### Install and Use v-skill Directive Globally in Vue.js

Source: https://skilltreeplatform.dev/skills-client/legacy

Globally install the SkillsDirective in your Vue application's entry point (e.g., main.js or App.vue) to enable the v-skills directive for reporting skill events.

```javascript
import { SkillsDirective } from '@skilltree/skills-client-vue';

Vue.use(SkillsDirective);

```

--------------------------------

### CURL: Get User Auth Token

Source: https://skilltreeplatform.dev/skills-client/auth

This CURL command demonstrates how to authenticate with the SkillTree dashboard to retrieve a user's authentication token. It sends a POST request with `client_credentials` grant type and specifies the proxy user. Remember to replace the placeholder values for `client-id`, `client-secret`, `dashboard-url`, and `user-to-proxy-for` with your actual credentials.

```bash
curl client-id:client-secret@dashboard-url/oauth/token -d "grant_type=client_credentials&proxy_user=user-to-proxy-for"
```

--------------------------------

### Configure WebSocket Stomp Broker Relay in SkillTree

Source: https://skilltreeplatform.dev/dashboard/install-guide/prodInstall

Enables the WebSocket Stomp Broker Relay for real-time communication in SkillTree. You need to provide the host and port of your configured Stomp broker (e.g., RabbitMQ, Amazon MQ).

```properties
skills.websocket.enableStompBrokerRelay=true
skills.websocket.relayHost=
skills.websocket.relayPort=
```

--------------------------------

### Initialize Skills Display with Versioning

Source: https://skilltreeplatform.dev/skills-client/js

This example shows how to initialize the SkillsDisplayJS component when using Skills Versioning. It passes a `version` number to the constructor within the `afterConfigure` callback to specify the desired version.

```javascript
SkillsConfiguration.afterConfigure().then(() => {
    const clientDisplay = new SkillsDisplayJS({
        version: 1,
    });
});
```

--------------------------------

### Azure AD Integration

Source: https://skilltreeplatform.dev/dashboard/install-guide/installModes

Configure your Azure AD application registration details to enable OAuth-based login for the SkillTree platform.

```APIDOC
## Azure AD Configuration

### Description
Configure these properties in your application's configuration file to integrate with Azure Active Directory for OAuth authentication.

### Method
N/A (Configuration Properties)

### Endpoint
N/A

### Parameters
#### Request Body
- **spring.security.oauth2.client.registration.azure.client-id** (string) - Required - The client ID from your Azure App Registration.
- **spring.security.oauth2.client.registration.azure.client-secret** (string) - Required - The client secret from your Azure App Registration.
- **spring.security.oauth2.client.registration.azure.redirect-uri** (string) - Required - The redirect URI configured in your Azure App Registration. Use `https://<SkillTree Dashboard URL>/{action}/oauth2/code/{registrationId}`.
- **spring.security.oauth2.client.registration.azure.iconClass** (string) - Optional - CSS class for the login button icon (e.g., `fab fa-microsoft`).
- **spring.security.oauth2.client.registration.azure.scope** (string) - Optional - Scopes to request from Azure AD (e.g., `openid,profile,email`). Defaults to `openid,profile,email`.
- **spring.security.oauth2.client.registration.azure.authorization-grant-type** (string) - Optional - Authorization grant type. Defaults to `authorization_code`.
- **spring.security.oauth2.client.registration.azure.client-name** (string) - Optional - The name displayed for the Azure AD login option. Defaults to `Azure`.
- **spring.security.oauth2.client.registration.azure.provider** (string) - Optional - The provider alias. Defaults to `azuread`.

### Azure AD Provider Configuration

- **spring.security.oauth2.client.provider.azuread.authorization-uri** (string) - Required - The authorization endpoint URI for Azure AD.
- **spring.security.oauth2.client.provider.azuread.token-uri** (string) - Required - The token endpoint URI for Azure AD.
- **spring.security.oauth2.client.provider.azuread.user-info-uri** (string) - Required - The user info endpoint URI for Azure AD.
- **spring.security.oauth2.client.provider.azuread.jwk-set-uri** (string) - Required - The JWK set URI for Azure AD.

### Request Example
```properties
spring.security.oauth2.client.registration.azure.client-id=YOUR_AZURE_CLIENT_ID
spring.security.oauth2.client.registration.azure.client-secret=YOUR_AZURE_CLIENT_SECRET
spring.security.oauth2.client.registration.azure.redirect-uri=https://your-skilltree.com/skilltree/oauth2/code/azure
spring.security.oauth2.client.provider.azuread.authorization-uri=https://login.microsoftonline.com/common/oauth2/v2.0/authorize
spring.security.oauth2.client.provider.azuread.token-uri=https://login.microsoftonline.com/common/oauth2/v2.0/token
spring.security.oauth2.client.provider.azuread.user-info-uri=https://graph.microsoft.com/oidc/userinfo
spring.security.oauth2.client.provider.azuread.jwk-set-uri=https://login.microsoftonline.com/common/discovery/keys
```

### Response
N/A (Configuration properties do not have direct request/response)

### Error Handling
Excluding a provider configuration section will prevent the respective OAuth login button from being added to the Login page.
```

--------------------------------

### Java: Report Skill for Another User (Admin)

Source: https://skilltreeplatform.dev/skills-client/endpoints

This Java example shows how a project admin can report a skill for a different user. It requires the same credentials as the basic report example but additionally takes another user's ID. This functionality is only available if the token's associated user has administrative privileges for the project.

```Java
public class ReportForAnotherUserExample {

    public static void main(String[] args) throws Exception {
        // "Client Id" and "Client Secret" found under 
        // "Trusted Client Properties" on project's "Access" page
        ReportForAnotherUserExample reportJavaExample = 
                new ReportForAnotherUserExample(
                        "<PROJECT_ID>", 
                        "<SECRET>", 
                        "<PROTOCOL>", 
                        "<HOST>");
        // must be an admin of <project_id>
        String token = reportJavaExample.getToken("<USER_ID>");
        String res = reportJavaExample.reportSkillForAnother(
                token, 
                "<ANOTHER_USER_id>", 
                "<SKILL_ID>", 
                new Date());
        System.out.println(res);
    }
    
    private final String projectId;
    private final String secret;
    private final String protocol;
    private final String host;

    public ReportForAnotherUserExample(
            String projectId, String secret, 
            String protocol, String host) {
        this.projectId = projectId;
        this.secret = secret;
        this.protocol = protocol;
        this.host = host;
    }

    public String getToken(String userID) throws Exception {
        String authUrl = protocol + "://"+ 
                projectId + ":" + secret + "@" + host + "/oauth/token";

        // First setup token
        List<NameValuePair> authParameters = new ArrayList<>();
        authParameters.add(
                new BasicNameValuePair("grant_type", "client_credentials"));

```

--------------------------------

### Vue.js Skills Display Component Initialization

Source: https://skilltreeplatform.dev/dashboard/user-guide/skills

Example of initializing the skills display component in Vue.js with a specified version. This component is used to visualize the skill profile for a given version.

```html
<skills-display version="0"/>

```

```html
<skills-display version="1"/>

```

--------------------------------

### Example: Toast Notifications for Skill Events - TypeScript

Source: https://skilltreeplatform.dev/skills-client/legacy

This TypeScript example illustrates a component that registers a global success handler to display toast messages for various skill completion events. It iterates through completed items and dispatches specific messages based on the event type (Overall, Subject, Skill, Badge). The `displayToast` method is application-specific and omitted.

```typescript
export class ToastExampleComponent 
    registerToDisplayProgress() {
        const myGlobalSuccessHandler = (result) => {
          if (result.completed) {
            result.completed.forEach((completedItem) => {
              this.handleEvent(completedItem);
            });
          }
        };
        SkillsReporter.addSuccessHandler(myGlobalSuccessHandler);
    }

    handleEvent(completedItem) {
        let title = '';
        let msg = '';
        switch (completedItem.type) {
        case 'Overall':
          title = `Level ${completedItem.level}!!!!`;
          msg = `Wow! Congratulations on the Overall Level ${completedItem.level}!`;
          break;
        case 'Subject':
          title = 'Subject Level Achieved!!';
          msg = `Impressive!! Level ${completedItem.level} in ${completedItem.name} subject!`;
          break;
        case 'Skill':
          title = 'Skill Completed!!';
          msg = `Way to complete ${completedItem.name} skill!!!`;
          break;
        case 'Badge':
          title = `${completedItem.name}!!!`;
          msg = `You are now a proud owner of ${completedItem.name} badge!!!`;
          break;
        default:
          title = 'Completed!!';
          msg = `Way to finish ${completedItem.name}!`;
        }
        
        this.displayToast(msg, title);
    }
}
```

--------------------------------

### Display Skilltree Skills using Angular Component

Source: https://skilltreeplatform.dev/skills-client/legacy

Provides an example of an Angular single-file component that uses the `<skills-display/>` component to visualize a user's skill profile. It demonstrates basic component structure and template usage.

```typescript
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <div class="container">
        <skills-display/>
    </div>
  `,
})
export class ShowSkillsComponent {
  constructor() { }
}

```

--------------------------------

### Configure Spring Session for JDBC in SkillTree

Source: https://skilltreeplatform.dev/dashboard/install-guide/prodInstall

This configuration enables SkillTree to use JDBC for persisting HTTP sessions, which is recommended for clustered environments. It utilizes the existing PostgreSQL database for simplicity.

```properties
spring.session.store-type=jdbc
spring.session.jdbc.initialize-schema=always
```

--------------------------------

### User Info Service - User Details JSON Payload

Source: https://skilltreeplatform.dev/dashboard/install-guide/installModes

This JSON structure represents the expected response from the `skills.authorization.userInfoUri` endpoint when retrieving user information by DN. It includes essential user metadata.

```json
{
    "firstName":"<value>",
    "lastFirstName":"<value>",
    "email":"<value>",
    "username":"<value>",
    "userDn":"<value>",
    "usernameForDisplay":"<value>"
}
```

--------------------------------

### Programmatic Navigation in Skills Display

Source: https://skilltreeplatform.dev/skills-client/js

This example illustrates how to programmatically navigate within the Skills Client Display component using the `navigate()` method. It includes a button to trigger navigation to a specific path, '/subjects/subj0'.

```javascript
<button type="button" onclick="navigate()">Navigate</button>
  
navigate() {
  this.clientDisplay.navigate('/subjects/subj0')
}
}
```

--------------------------------

### User Info Service - User Query Results JSON Payload

Source: https://skilltreeplatform.dev/dashboard/install-guide/installModes

This JSON structure represents the expected response from the `skills.authorization.userQueryUri` endpoint. It is a list of user objects that match the query criteria, used for suggestions in SkillTree dashboard dropdowns.

```json
[
    {
        "firstName":"<value>",
        "lastFirstName":"<value>",
        "email":"<value>",
        "username":"<value>",
        "userDn":"<value>",
        "usernameForDisplay":"<value>"
    },
    {
        "firstName":"<value>",
        "lastFirstName":"<value>",
        "email":"<value>",
        "username":"<value>",
        "userDn":"<value>",
        "usernameForDisplay":"<value>"
    }
]
```

--------------------------------

### User Info Service 2-way SSL Client Authentication Properties (Java System Properties)

Source: https://skilltreeplatform.dev/dashboard/install-guide/prodInstall

Specifies Java System Properties for client authentication when the User Info Service utilizes 2-way SSL. This includes configuration for the keystore and truststore, essential for secure communication between services.

```properties
# Keystore
-Djavax.net.ssl.keyStore=/certs/keystore.p12
-Djavax.net.ssl.keyStoreType=PKCS12
-Djavax.net.ssl.keyStorePassword=

# Truststore
-Djavax.net.ssl.trustStore=/certs/truststore.p12
-Djavax.net.ssl.trustStoreType=PKCS12
-Djavax.net.ssl.trustStorePassword=
```

--------------------------------

### Java: Report Skill for a User

Source: https://skilltreeplatform.dev/skills-client/endpoints

This Java example demonstrates how to retrieve an authentication token for a specific user and then report a skill for that same user. It requires project ID, client secret, protocol, host, user ID, and skill ID as inputs. The token is obtained using client credentials, and the skill is reported via an API POST request.

```Java
public class ReportExample {

    public static void main(String[] args) throws Exception {
        // "Client Id" and "Client Secret" found under 
        // "Trusted Client Properties" on project's "Access" page
        ReportExample reportJavaExample = 
                new ReportExample(
                        "<PROJECT_ID>", 
                        "<SECRET>", 
                        "<PROTOCOL>", 
                        "<HOST>");
        String token = reportJavaExample.getToken("<USER_ID>");
        String res = reportJavaExample.reportSkill(token, "<SKILL_ID>");
        System.out.println(res);
    }


    private final String projectId;
    private final String secret;
    private final String protocol;
    private final String host;

    public ReportExample(String projectId, 
                         String secret, 
                         String protocol, 
                         String host) {
        this.projectId = projectId;
        this.secret = secret;
        this.protocol = protocol;
        this.host = host;
    }

    public String getToken(String userID) throws Exception {
        String authUrl = protocol + "://"+ projectId + 
                ":" + secret + "@" + host + "/oauth/token";

        List<NameValuePair> authParameters = new ArrayList<>();
        authParameters.add(
                new BasicNameValuePair("grant_type", "client_credentials"));
        authParameters.add(
                new BasicNameValuePair("proxy_user", userID));
        HttpPost authPost = new HttpPost(authUrl);
        authPost.setEntity(new UrlEncodedFormEntity(authParameters));

        String token = "";
        try (CloseableHttpClient httpClient = HttpClients.createDefault();
             CloseableHttpResponse response = httpClient.execute(authPost)) {
            String tokenInfo = EntityUtils.toString(response.getEntity());
            JSONObject tokenJson = new JSONObject(tokenInfo);
            token = (String) tokenJson.get("access_token");
        }

        return token;
    }

    public String reportSkill(String token, String skillId) 
            throws Exception {
        String reportUrl = protocol + "://"+ 
                host + "/api/projects/" + projectId + "/skills/" + skillId;

        HttpPost post = new HttpPost(reportUrl);
        post.setHeader("Authorization", "Bearer " + token);

        try (CloseableHttpClient httpClient = HttpClients.createDefault();
             CloseableHttpResponse response = httpClient.execute(post)) {
            return EntityUtils.toString(response.getEntity());
        }
    }
}

```

--------------------------------

### User Info Service Client Properties for skills-service

Source: https://skilltreeplatform.dev/dashboard/install-guide/prodInstall

Defines the URIs for the User Info Service, which provides user details based on Distinguished Names (DN). Includes properties for retrieving user info, querying users for dashboard suggestions, and health checking the User Info Service. These are essential for integrating external user management.

```properties
# To retrieve user info by DN
skills.authorization.userInfoUri=https://<host>:<port>/userInfo?dn={dn}
# Used by dashboard dropdowns to suggest existing users
skills.authorization.userQueryUri=https://<host>:<port>/userQuery?query={query}
# skills-service checks the health of User Info Service
skills.authorization.userInfoHealthCheckUri=https://<host>:<port>/actuator/health
```

--------------------------------

### skills-service PKI Authentication Mode Configuration

Source: https://skilltreeplatform.dev/dashboard/install-guide/prodInstall

Enables the Public Key Infrastructure (PKI) authentication mode for the skills-service. This setting dictates that user authentication will be handled via PKI certificates. The 'authMode' property must be set to 'PKI'.

```properties
skills.authorization.authMode=PKI
```

--------------------------------

### skills-service HTTPS and 2-way SSL Configuration

Source: https://skilltreeplatform.dev/dashboard/install-guide/prodInstall

Configures the skills-service to use HTTPS with 2-way SSL for secure communication. This involves setting the server port, enabling SSL, requiring client authentication, specifying enabled protocols (TLSv1.2), and defining paths and passwords for the keystore and truststore.

```properties
server.port=8443
server.ssl.enabled=true
server.ssl.client-auth=want
	
# Force TLSv1.2 until https://bugs.openjdk.java.net/browse/JDK-8241248 is fixed
server.ssl.enabled-protocols=TLSv1.2

# keystore
server.ssl.key-store=/certs/keystore.p12
server.ssl.key-store-password=
server.ssl.keyStoreType=PKCS12

# truststore
server.ssl.trust-store=/certs/truststore.p12
server.ssl.trust-store-password=
server.ssl.trustStoreType=PKCS12
```

--------------------------------

### Configure GitHub OAuth2 Authentication for SkillTree

Source: https://skilltreeplatform.dev/dashboard/install-guide/installModes

These properties configure the SkillTree dashboard to use GitHub for OAuth2-based authentication. Requires GitHub client ID and secret credentials. The redirect URI must be set to match your SkillTree dashboard host.

```properties
# GitHub
spring.security.oauth2.client.registration.github.client-id=<GitHub client id here>
spring.security.oauth2.client.registration.github.client-secret=<GitHub client secret here>
spring.security.oauth2.client.registration.github.redirectUriTemplate='https://<SkillTree Dashboard Host>/{action}/oauth2/code/{registrationId}'
spring.security.oauth2.client.registration.github.iconClass=fab fa-github
```

--------------------------------

### Enable Keystore for JWT Generation in SkillTree

Source: https://skilltreeplatform.dev/dashboard/install-guide/prodInstall

This setting allows SkillTree to use the same keystore file for JSON Web Token (JWT) generation when running in HTTPS SSL mode. This is a required step for clustered deployments needing JWT generation.

```properties
security.oauth2.jwt.useKeystore=true
```

--------------------------------

### Configure Google OAuth2 Authentication for SkillTree

Source: https://skilltreeplatform.dev/dashboard/install-guide/installModes

These properties configure the SkillTree dashboard to use Google for OAuth2-based authentication. Requires Google client ID and secret credentials. The redirect URI must be set to match your SkillTree dashboard host.

```properties
# Google
spring.security.oauth2.client.registration.google.client-id=<Google client id here>
spring.security.oauth2.client.registration.google.client-secret=<Google client secret here>
spring.security.oauth2.client.registration.google.redirectUriTemplate='https://<SkillTree Dashboard Host>/{action}/oauth2/code/{registrationId}'
spring.security.oauth2.client.registration.google.iconClass=fab fa-google
```

--------------------------------

### Handle Skill Events and Display Toast Messages

Source: https://skilltreeplatform.dev/skills-client/legacy

An example demonstrating how to register a custom success handler that iterates through completed skills and dispatches specific actions based on the type of completion (Overall, Subject, Skill, Badge). It calls a displayToast method for each event, with the implementation details omitted.

```javascript
methods: {
    registerToDisplayProgress() {
        const myGlobalSuccessHandler = (result) => {
          if (result.completed) {
            result.completed.forEach((completedItem) => {
              this.handleEvent(completedItem);
            });
          }
        };
        SkillsReporter.addSuccessHandler(myGlobalSuccessHandler);
    },
    handleEvent(completedItem) {
        let title = '';
        let msg = '';
        switch (completedItem.type) {
        case 'Overall':
          title = `Level ${completedItem.level}!!!!`;
          msg = `Wow! Congratulations on the Overall Level ${completedItem.level}!`;
          break;
        case 'Subject':
          title = 'Subject Level Achieved!!';
          msg = `Impressive!! Level ${completedItem.level} in ${completedItem.name} subject!`;
          break;
        case 'Skill':
          title = 'Skill Completed!!';
          msg = `Way to complete ${completedItem.name} skill!!!`;
          break;
        case 'Badge':
          title = `${completedItem.name}!!!`;
          msg = `You are now a proud owner of ${completedItem.name} badge!!!`;
          break;
        default:
          title = 'Completed!!';
          msg = `Way to finish ${completedItem.name}!`;
        }
        
        this.displayToast(msg, title);
    },
}

```

--------------------------------

### Report Single Skill Event - HTTP POST

Source: https://skilltreeplatform.dev/skills-client/endpoints

This example shows a direct HTTP POST request to the SkillTree API endpoint for reporting a single skill event. It specifies the service URL, project ID, and skill ID in the URL path.

```http
POST http://localhost:8080/api/projects/ProjectA/skills/SkillA
```