SkillTree Docs

# Quick Start

The steps to getting started with SkillTree are:

  1. Prerequisites - don't worry there isn't much here
  2. Install and Start the Dashboard and create your project
  3. (Optional) Integrate Client Libraries into your application (examples will be provided)

Please Note

Please note that the integrating the SkillTree Client Libraries is optional and is only applicable when integrating gamification training directly into an existing or new web application.

# 1. Prerequisites

TIP

If a PosgtgreSQL database is not already available, one can easily be started using a docker container (see example below), or visit the official please documentation https://www.postgresql.org for other installation options.

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

# 2. Install & Start Dashboard and Service

You have 2 options:

  • Option 1 - utilize a pre-built docker image
  • Option 2 - download and run the jar-based distribution

# Option 1 - Docker-based install

The skills-service docker image is hosted on DockerHub and can be started like this:

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

IMPORTANT

Please note that the latest tag is not published to DockerHub and :<tag_version> must be specified explicitly. Available tags can be found on DockerHub tags page .

You can tail the application logs via:

docker logs -f <container_id>

Your output will look something like this (the majority of the output was omitted for brevity):

 .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::       (vX.X.X.RELEASE)
...
...
...
2020-07-16 19:43:01.129  INFO 9103 --- [           main] o.s.m.s.b.SimpleBrokerMessageHandler     : Started.
2020-07-16 19:43:01.189  INFO 9103 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2020-07-16 19:43:01.192  INFO 9103 --- [           main] skills.SpringBootApp                     : Started SpringBootApp in 20.159 seconds (JVM running for 21.368)

The dashboard is now running on http://localhost:8080 (opens new window).

Well... that's it!

The next step is to start the java-backend-example service which:

  1. Populates the skills-service with sample data
  2. Implements an example Authentication Endpoint that's required to run client components

Download the latest java-backend-example from skills-client-examples/releases 

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

Start java-backend-example using the downloaded jar (make sure to substitute X.X.X for an actual version):

java -jar java-backend-example-X.X.X.jar

Please note that java-backend-example populates the skills-service with sample data so it may take few minutes to start. Once sample data population has completed, the following line appears on standard out:

o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8090 (http) with context path ''

On start, java-backend-example populates the skills-service with a sample project named Movies. Once it starts, logout from the dashboard and log back in as

  • username=bill@email.org
  • password=password and explore the sample Movies project.

# Option 2 - Jar-based install

Download the latest .jar release from GitHub skills-service/releases/ (under the Assets section).

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

Using the downloaded jar you can run the SkillTree dashboard and service (make sure to substitute X.X.X for an actual version):

$ 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

Your output will look something like this (the majority of the output was omitted for brevity):

 .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::       (vX.X.X.RELEASE)
...
...
...
2020-07-16 19:43:01.129  INFO 9103 --- [           main] o.s.m.s.b.SimpleBrokerMessageHandler     : Started.
2020-07-16 19:43:01.189  INFO 9103 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2020-07-16 19:43:01.192  INFO 9103 --- [           main] skills.SpringBootApp                     : Started SpringBootApp in 20.159 seconds (JVM running for 21.368)

The dashboard is now running on http://localhost:8080 (opens new window).

Well... that's it!

The next step is to start the java-backend-example service which:

  1. Populates the skills-service with sample data
  2. Implements an example Authentication Endpoint that's required to run client components

Download the latest java-backend-example from skills-client-examples/releases 

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

Start java-backend-example using the downloaded jar (make sure to substitute X.X.X for an actual version):

java -jar java-backend-example-X.X.X.jar

Please note that java-backend-example populates the skills-service with sample data so it may take few minutes to start. Once sample data population has completed, the following line appears on standard out:

o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8090 (http) with context path ''

On start, java-backend-example populates the skills-service with a sample project named Movies. Once it starts, logout from the dashboard and log back in as

  • username=bill@email.org
  • password=password and explore the sample Movies project.

# 3. Integrate Client Libraries

Please Note

Please note that integrating the SkillTree Client Libraries is optional and is only applicable when integrating gamification training directly into an existing or new web application.

This section assumes that you already have running

  • skills-service on port 8080
  • java-backend-example on port 8090

Below are the directions for each supported library, please proceed to one of your liking:

# Option 1 - Vue.js Example

To run the Hello World Vue.js example, clone the skills-client-examples project and start the Vue development server:

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

Vue CLI displays the development server url at startup, it will likely be this: http://localhost:8081/ (opens new window)

If you want to build the Hello World Vue.js application yourself, here are the steps:

TIP

This example uses Vue CLI to quickly scaffold a Single Page Application.

npm install -g @vue/cli
vue create vuejs-example
# accept all of the defaults, press enter
cd vuejs-example
npm run serve

Feel free to check out the Vue.js splash page then kill the server. Let's install and use some of the SkillTree components.

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

Configure SkillTree:

main.js



 



 
 
 
 
 
 





import Vue from 'vue'
import App from './App.vue'
import { SkillsDirective, SkillsConfiguration } from '@skilltree/skills-client-vue';

Vue.config.productionTip = false

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

new Vue({
  render: h => h(App),
}).$mount('#app')

TIP

In a production environment we'd configure these resources using the https protocol. Please review the Authentication and Configuration sections for greater detail.

Copy the HelloWorld components from skills-client-examples/vuejs-example/src/components:

  • HelloWorldSkillsDisplay.vue - Pluggable user skill and ranking visualization
  • HelloWorldSkillsEventReporting.vue - Report Skill Events when user preforms actions in the application
  • HelloWorldGlobalEventHandler.vue - Handle event reporting results in one place

Now you can use these components in App.vue:

<template>
    <div>
        <h1>Current User's Skills Display</h1>
        <hello-world-skills-display/>
        <h1>Report Skill Events</h1>
        <hello-world-skills-event-reporting/>
        <h3>Result:</h3>
        <hello-world-global-event-handler/>
    </div>
</template>

<script>
    import HelloWorldSkillsDisplay from "./components/HelloWorldSkillsDisplay";
    import HelloWorldSkillsEventReporting from "./components/HelloWorldSkillsEventReporting";
    import HelloWorldGlobalEventHandler from "./components/HelloWorldGlobalEventHandler";

    export default {
        name: 'App',
        components: {
            HelloWorldGlobalEventHandler,
            HelloWorldSkillsEventReporting,
            HelloWorldSkillsDisplay,
        }
    }
</script>

<style>
    body {
        margin: 0px;
        padding-bottom: 3rem;
        text-align: center;
    }
</style>

For further details regarding integrating SkillTree into your application, please visit our Integration Guide.

# Option 2 - React Integration Example

To run the Hello World React example clone the skills-client-examples project and start the React development server:

git clone git@github.com:NationalSecurityAgency/skills-client-examples.git
cd skills-client-examples/react-example
npm install
npm run start

React CLI displays the development server url at startup, it will likely be this: http://localhost:3000 (opens new window)

If you want to build the Hello World React application yourself, here are the steps:

TIP

This example uses Create React App to quickly scaffold a Single Page Application.

npm install -g create-react-app
create-react-app react-example
cd react-example
npm run start

Feel free to check out the React splash page then kill the server. Let's install and use some of the SkillTree components.

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

Configure SkillTree:

index.js






 

 
 
 
 
 









import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';
import { SkillsConfiguration } from '@skilltree/skills-client-react';

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

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('root')
);
serviceWorker.unregister();

TIP

In a production environment we'd configure these resources using the https protocol. Please review the Authentication and Configuration sections for greater detail.

Copy the HelloWorld components from skills-client-examples/react-example/src/skilltree:

  • HelloWorldSkillsDisplay.js - Pluggable user skill and ranking visualization
  • HelloWorldSkillsEventReporting.js - Report Skill Events when user preforms actions in the application
  • HelloWorldGlobalEventHandler.js - Handle event reporting results in one place

Now you can use these components in App.js:



 
 
 





 


 

 






import React from 'react';
import './App.css';
import HelloWorldSkillsDisplay from './HelloWorldSkillsDisplay';
import HelloWorldSkillsEventReporting from './HelloWorldSkillsEventReporting';
import HelloWorldGlobalEventHandler from './HelloWorldGlobalEventHandler';

function App() {
  return (
    <div className="App">
        <h1>Current User's Skills Display</h1>
        <HelloWorldSkillsDisplay />

        <h1>Report Skill Events</h1>
        <HelloWorldSkillsEventReporting />
        <h3>Result:</h3>
        <HelloWorldGlobalEventHandler />
    </div>
  );
}

export default App;

For further details regarding integrating SkillTree into your application, please visit our Integration Guide.

# Option 3 - Angular Integration Example

To run the Hello World Angular example, clone the skills-client-examples project and start the Angular development server:

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

Angular CLI displays the development server url at startup, it will likely be this: http://localhost:4200/ (opens new window)

If you want to build the Hello World Angular application yourself, here are the steps:

TIP

This example uses Angular CLI to quickly scaffold a Single Page Application.

npm install -g @angular/cli
ng new ng-example
# accept all of the defaults, press enter
cd ng-example
npm run start

Feel free to check out the Angular splash page then kill the server. Let's install and use some of the SkillTree components.

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

Configure SkillTree:

main.ts

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 




import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { SkillsConfiguration } from '@skilltree/skills-client-ng';

import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

if (environment.production) {
  enableProdMode();
}

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

platformBrowserDynamic().bootstrapModule(AppModule)
  .catch(err => console.error(err));

TIP

In a production environment we'd configure these resources using the https protocol. Please review the Authentication and Configuration sections for greater detail.

Copy the HelloWorld components from skills-client-examples/ng-example/src/app/components/*/*.ts to src/app/:

  • hello-world-skills-display.component.ts - Pluggable user skill and ranking visualization
  • hello-world-event-reporting.component.ts - Report Skill Events when user preforms actions in the application
  • hello-world-global-event-reporting.component.ts - Handle event reporting results in one place

Now you can import and declare the components in app.module.ts:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { SkillsLevelModule, SkillsDisplayModule, SkilltreeModule } from '@skilltree/skills-client-ng'

import { AppComponent } from './app.component';
import { HelloWorldGlobalEventHandlerComponent } from './hello-world-global-event-handler.component';
import { HelloWorldSkillsDisplayComponent } from './hello-world-skills-display.component';
import { HelloWorldEventReportingComponent } from './hello-world-event-reporting.component';

@NgModule({
  declarations: [
    AppComponent,
    HelloWorldGlobalEventHandlerComponent,
    HelloWorldSkillsDisplayComponent,
    HelloWorldEventReportingComponent
  ],
  imports: [
    BrowserModule,
    SkillsLevelModule,
    SkilltreeModule,
    SkillsDisplayModule,
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

...and use the components in app.component.ts:

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

@Component({
  selector: 'app-root',
  template: `
  <div>
    <div>
      <h1>Current User's Skills Display</h1>
        <app-hello-world-skills-display></app-hello-world-skills-display>
      <h1>Report Skill Events</h1>
        <app-hello-world-event-reporting></app-hello-world-event-reporting>
      <h3>Result:</h3>
        <app-hello-world-global-event-handler></app-hello-world-global-event-handler>
    </div>
  </div>
  `,
  styles: [`
    pre {
      margin: auto;
      padding: 1rem;
      border: 1px solid #dddddd !important;
      overflow: auto;
      border-radius: 6px;
      background-color: #f6f8fa;
      min-height: 3rem;
      max-width: 80rem;
    
    }
    
    .res {
      text-align: left;
    }
  `]
})
export class AppComponent {
  title = 'ng-example';
}

For further details regarding integrating SkillTree into your application, please visit our Integration Guide.

# Option 4 - Pure JS Integration Example

To run the Hello World Pure JS example, clone the skills-client-examples project and start the live-server development server:

git clone git@github.com:NationalSecurityAgency/skills-client-examples.git
cd skills-client-examples/js-example
npm install
npm run serve
live-server displays the development server url at startup, it will likely be this:

http://127.0.0.1:8092 (opens new window)

If you want to build the Hello World Pure JS application yourself, here are the steps:

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

You can install the SkillTree JS lib using npm:

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

However, these examples will utilize <script> tags to import the SkillTree library:

<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 the SkillTree client library - this only needs to happen once per user session:

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

TIP

In a production environment we'd configure these resources using the https protocol. Please review the Authentication and Configuration sections for greater detail.

Pluggable user skill and ranking visualization:

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

Report Skill Events when a user performs actions in the application:

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

Handle event reporting results in one place:

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

The full example can be found @ skills-client-examples/js-example/index.html

Now start the server:

npx live-server --no-browser --port=8092 --open=app --cors --proxy=/api:http://localhost:8090/api --proxy=/native:http://localhost:8092/
live-server displays development server url on startup, it will likely be this:

http://127.0.0.1:8092 (opens new window).

For further details regarding integrating SkillTree into your application, please visit our Integration Guide.

Last Updated: 9/25/2023, 2:55:06 PM