Integrator's Guide

Refers to a previous version — updates coming soon!

Activator Quick Start

These instructions will get the Kgrid Activator running with sample set of Knowledge Objects.

Prerequisites

For running the application you need:

Running the Activator

Download the latest activator jar from GitHub Latest Activator Release.

  1. Create a activator directory
  2. Create a directory named shelf in the new activator directory
  3. Download kgrid-activator-#.#.#.jar
  4. Place the kgrid-activator-#.#.#.jar into the activator
  5. Download hello-world.zip
  6. Place the hello-world.zip into the activator/shelf directory and unzip. This will place the KOs into the shelf directory

Directory structure should look similar to the following

 ├── activator   
 │  └──  shelf
 │     └── hello-world  
 │        └── v0.0.1
 │           ├── model
 │           └── metadata.json
 └── kgrid-activator-#.#.#.jar

The activator is executable jar and can be run from the command line. Open a terminal window and navigate to the direcoty where the jar and shelf are located.

Type in the following.

 java -jar kgrid-activator-#.#.#.jar

By default the activator will run on port 8080. You can validate the activator is up and running using the activators health endpoint. The health of the Activator should display a status of UP.

{
   "status": "UP",
   "shelf": {
      "status": "UP",
      "kgrid.shelf.cdostore.url": "shelf"
   },
   "activationService": {
      "status": "UP",
      "Knowledge Objects found": 1,
      "Adapters loaded": [
        "JAVASCRIPT",
        "PROXY"
       ],
   "EndPoints loaded": [
        "hello/world/v0.0.1/welcome"
   ]
   },
   "diskSpace": {
      "status": "UP",
      "total": 499963170816,
      "free": 415911948288,
      "threshold": 10485760
   }
 }

Using the Hello World KO on the Activator

The Hello World is a very simple KO with a Javascript based service that takes in a name and displays a Welcome to the Knowledge Grid message.

First lets look at the Hello World's metadata. Hello World

The Hello World KO has one service called welcome. The welcome service expects you to pass it a name as a json object, for example {"name":"Fred Flintstone"}. The following is a curl POST to the Hello World welcome.

curl -X POST -H "Content-Type:application/json"  \
    -d "{\"name\": \"Fred Flintstone\"}" \
     http://localhost:8080/hello/world/v0.0.1/welcome

The Hello World KO will return the following

{
    "result": "Welcome to Knowledge Grid, Fred Flintstone",
    "info": {
        "ko": "hello/world/v0.0.1",
        "inputs": {
            "name": "Fred Flintstone"
        }
    }
}

Library Quick Start

These instructions will get the Kgrid Library running with sample set of Knowledge Objects.

Prerequisites

For running the application you need:

Running the Library

Download the latest library jar from GitHub Latest Activator Release.

  1. Create a library directory
  2. Download kgrid-library-#.#.#.jar
  3. Place the kgrid-library-#.#.#.jar into the library
  4. Create a directory named shelf in the new library directory

Directory structure should look similar to the following

 └── library
     └── shelf  
     └── kgrid-library-#.#.#.jar

The library is executable jar and can be run from the command line. Open a terminal window and navigate to the directory where the jar and shelf are located.

Type in the following.

 java -jar kgrid-library-#.#.#.jar

By default the activator will run on port 8080. You can validate the activator is up and running using the library health endpoint. The health of the Activator should display a status of UP.

{
   status: "UP",
   userDetailService: {
     status: "UP",
     number of users: 2
    }  ,
    ezidService: {
      status: "UP",
      ezid.base.url: "https://ezid.lib.purdue.edu/",
      ezid.mock: "false"
    },
    shelf: {
      status: "UP",
      kgrid.shelf.cdostore.url: "/Users/me/library/shelf"
    },
    diskSpace: {
      status: "UP",
      total: 402672611328,
      free: 269428576256,
      threshold: 10485760
    },
      db: {
      status: "UP",
      database: "H2",
      hello: 1
    }
}

Now simply navigate to the KGrid Library.

Adding the Hello World KO on the Library

The Library allows you to take deposit a Knowledge Object archive (zip file). On the KGrid Library main page you will see a Deposit Knowledge Object.

  1. Download hello-world.zip
  2. Navigate to the KGrid Library site.
  3. Follow this screen flow

Click on Deposit Knowledge Object in the right side of the screen

Click in the grey box to bring up a file select window.

Select the hello-world.zip you just downloaded and click Deposit Object in the lower right of the screen.

The file will be upload to the library and you return to library main screen.

Example Collection

This repository contains a collection of KGrid Knowledge Objects that demonstrate features of the grid, good development practices and useful tools.

Anatomy of this Knowledge Object project.

The following structure is not an requirement or enforced, it is a recommendation based on what the JavaScript and in particular Node community at large have been following by convention.

Prerequisites

There are testing and packaging features in this project that require npm, npm is installed with Node.js npm. Once npm is installed run npm install at the root of this project.

Directories

  • collection/ contains one to many directories representing knowledge objects
    • naan-name is intended for each knowledge object (e.g. hello-world)
  • tests/ is for all of your project test scripts
  • etc/ is a sub-directory for miscellaneous project
  • docs/ is a sub-directory for more detailed information about these KOs
  • dist/ is created and destroyed when running npm run package
  • scripts/ is intended to capture various scripts need for the project (using scripty)
  • scriptswin/ windows versions of the scripts

Example Knowledge Objects

  • Hello World - Simple KO designed as a starting point. Demonstrates a project structure the includes unit testing and scripts to package the KO deposit.
  • BMI Calculator - Simple KO designed to calculate BMI based on height and weight. Demostrates passing mulitple attributes.
  • Minimum Viable - Simple KO designed demostrate the smallest amount of information needed to get KO

Bundled Object Example

Currently the KGrid Activator uses the Nashorn JavaScript engine for execution of JavaScript Objects. Nashorn implements ECMAScript 5.1 specification
This limits the tools and technics avalable to the KO developer. The KGrid has experimented with webpack and babel as a method to all the developer it until more current tools and techniques. Very simple example is Nashorn doesn't support const and let statements but use babel transpiler we can convert es6 to es5.

Please review Hello World bundle.v1 and bundle.v2 implementations.

Executive Object Example

Testing

Sample tests are located in the tests directory and can be executed using npm. These tests utilize Jest and rewire. est provides the testing framework and rewire allows the tests to access the javascript function without the convenience of the export modules (KGrid Javascript adaptor limitation). Each version of the object has a tests directory. You can execute the tests via npm

> npm test

Integration Testing

Running Example KOs in an Activator

You can now test the example objects in an activator via a npm script. This script will download the latest released activator and start up the activator using the example repository as it's shelf.

Open a terminal window at the root of the cloned repository and run the following command.

npm run dev

Package

You can create zip file of the Knowledge Object which can be used to deposit to a KGrid Library or load/activate on a KGrid Activator.

npm run package

Tools

NPM Tool

Last Updated: 7/25/2019, 2:00:08 PM