API seems overly complex, not sure how to authenticate and add points

[cybrpimp]

We are trying to figure out the API but it seems overly complex and not like a simple API Endpoint. Is there any more documentation or advice you can offer as we have been trying to use this for weeks now and unfortunately out of options.

[rmmayo]

hi @cybrpimp - sorry to hear you are having trouble. The authentication flow for password based SkillTree installation requires the client app to implement their own server side endpoint. This endpoint uses the project's client id and secret to obtain a token on behalf of the user logged into the client application.

The diagram below shows the typical flow:

1. User authenticates with the client web application.
2. The client web app requests a user token from their own backend server.
3. The client backend server uses the project client id and secret to obtain the user's token from the SkillTree backend server, which is sent back to the client web app.
4. The client web app reports skills to the SkillTree backend server. The token obtained in steps 2-3 is sent as an HTTP Header with each request.

The details for implementing your own endpoint to retrieve a user token is documented here. When configuring the SkillTree client library, use this endpoint URL for the authenticator property on the SkillsConfiguration.configure call. Further documentation can be found here.

Also, the Quick Start Guide shows a complete working example.

I hope this helps! Good luck!

[cybrpimp]

No did not help. As I said it is OVERLY COMPLEX. I've even had skilled developers try to figure this out and they said it is too confusing.

For some reason, all open issues are only from you and @sudo-may. So I suspect nobody else can figure out how to integrate to Skilltree either. Access to the API is a 100% necessary feature to integrate this app but so far nobody I have asked can figure it out?

Even the last project the Government-sponsored was only half complete and it failed to be very useful as it did not have a UI. https://github.com/ngageoint/gamification-server

So you guys implement a good UI, but leave out an easy solution for integration, while another government agency implements a good backend with easy integration but leaves out the UI.

Maybe you guys should work together to actually make a package people can actually use.

We work with APIs all day from Dropbox, Project managers, CRMs, and many others and never had this many problems.

This could be a great package to help many of today's new businesses having to build remote teams during Covid times, but when things are not simple, people just choose another package, as we will likely do.

It is very unfortunate as Skilltree seems to have the best dashboard and backend that I've seen.

I recommend a straightforward API endpoint built into the backend that is easy to use.

[mosefer]

Could you provide a specific example of what you're trying to accomplish? Then we may be able to better point you in the right direction. It might help if we take it step by step as to exactly what you've tried so far and exactly what you're attempting to do.

[cybrpimp]

Hey @mosefer , yes we just need a simple API endpoint that can be used to authenticate with a token & Add Points to Skilltree from our custom application.

For example, Redmine is one of the applications we use the API to integrate with and it is a simple process to authenticate and access.

https://www.redmine.org/projects/redmine/wiki/rest_api#Authentication

[mosefer]

@cybrpimp - will Skill events be reported via user interactions with a webapp or via REST interactions with a SkillTree instance? The authentication mechanism that SkillTree uses to report skills is a Oauth2 temporary client token approach. Depending on which integration approach you're taking, we could provide some guidance.

[cybrpimp]

@mosefer By the way, thanks for taking the time to help. It has been very frustrating as SkillTree is the best thing I've seen in 5 years of looking for a complete gamification solution.

I'm a little confused by your question but the fact you say "reported" I'm guessing you are talking more about how the User is going to see their rankings? If that is the case, I was planning on letting them log in via the dashboard. Eventually, it would be nice to use the REST API to pull their stats into our web app.

On the other hand, if you meant how will the SkillTree points (events) be "reported" meaning how are they added to the User's Account then in our case, a user is going to perform an action in our web app and the web app is going to make a REST API call to the SkillTree instance.

Sorry if I miss understood your question.

[mosefer]

@cybrpimp thanks and no worries, I'm going to take a step back to see if I can provide some guidance on setup and how it all fits together. We're also in the process of updating our documentation to hopefully make things a little clearer. So I'll start with the recommended implementation approach for your use case (integrating SkillTree into a webapp) and we can use that as a basis to discuss other approaches as necessary or where things aren't working for you. I may well re-state some things that you've already done but I think it'll help to get us all onto the same page.

Recommended approach:

1. Stand up an instance of the SkillTree dashboard/service - the easiest way is to use the available docker container
2. Create a Project using the SkillTree dashboard - this will contain the specific Skills you want users to accomplish (number of required repetitions, time between point awards, etc). The important thing to note here are the Skill IDs as these are what your webapp will report as users perform those actions.
   1. It's important to take note of the client-id and client-secret as we'll need these later - when viewing the Project you created in the SkillTree dashboard, these are available under the Access menu on the left:
3. In your webapp's backend, create an authentication endpoint, something like /users/{userid}/token - this end point, in your webapp's backend, is going to make a REST request to the SkillTree instance from step 1 and include your client-id and client-secret from earlier. It might seem convoluted but things are done this way so that your client-id and client-secret are never exposed to the browser. The details of this are covered in our docs but we definitely want to know if we haven't done a proper job of it yet.
4. Next is to integrate reporting of Skill events (i.e., when a user performs an action within your application that you would like them to earn points for). We provide npm libraries supporting Angular, React, Vue, and plain Javascript. These libraries make it relatively easy to report back to the SkillTree service/dashboard when a user performs an event you'd like them to receive points for. Docs covering reporting of Skill events in Vue.js for example.
   1. Note that before you start interacting with the SkillTree npm libraries in your webapp, you need to call SkillsConfiguration.configure when the page is loaded. In this case serviceUrl will point to the SkillTree instance deployed in Step 1. and authenticator will point to the endpoint created in YOUR webapp in step 3.
5. Now that you've got reporting of Skill events integrated you can integrate a display of the user's Ranking, the Skills they can accomplish, how many points they currently have, etc very easily and quickly. We provide an out-of-the box display component that gets you that display without any further work and can be integrated directly into your application. Example for Vue.js but each of the framework libraries we provide as well as the native Javascript libraries provide the same component.

So the biggest step that seems convoluted at the outset is the oauth2 authentication flow between your webapp's backend and the SkillTree instance. Now that we've got the recommended integration flow laid out in one place, what parts are you finding not to work for you? Part of the challenge is that we don't want to expose your Project's client-secret to the web-client as that would allow any user to potentially masquerade as any other user in the context of reporting Skill events and the out-of-the box display component that we provide.

[ceefour]

I also wrote a tutorial for this, hope this helps: https://about.lovia.life/docs/peopleops/skilltree/

[ceefour]

Thank you @mosefer for your clear explanation. Truly appreciate it.