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. Integrate Client Libraries into your application (examples will be provided)

# 1. Prerequisites

  • JDK 11+, we suggest Open JDK
    • Please note that this is not relevant if you elect to go with the Docker based install.
  • Git version 2.23+
  • Node.js v12+ and npm 6+

# 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 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 <external-url label="DockerHub tags page" url="https://hub.docker.com/r/skilltree/skills-service/tags".

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!

Good to Know!

Please note that the skills-service, by default, stores its data into an embedded in-memory H2 database. That data is ephemeral and will not persist between application restarts. While this is a great way to get started quickly, it is obviously not appropriate for a test or production installation. Please visit the Database Section to learn more.

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 -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!

Good to Know!

Please note that the skills-service, by default, stores its data into an embedded in-memory H2 database. That data is ephemeral and will not persist between application restarts. While this is a great way to get started quickly, it is obviously not appropriate for a test or production installation. Please visit the Database Section to learn more.

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

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: 12/13/2022, 2:52:20 PM