# KGrid Activator

# Running With Embedded JS Engine

Download the latest activator jar from GitHub Latest Activator Release.

  1. Create an 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-v1.0.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-v1.0  
      │       ├── metadata.json
      │       ├── service.yaml
      │       ├── deployment.yaml
      │       └── src
      │           └── index.js
      └── kgrid-activator-#.#.#.jar

The activator 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-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",
  "components" : {
    "activationService" : {
      "status" : "UP",
      "details" : {
        "kos" : 1,
        "endpoints" : 1
      }
    },
    "diskSpace" : {
      "status" : "UP",
      "details" : {
        "total" : 499514339328,
        "free" : 29091233792,
        "threshold" : 10485760,
        "exists" : true
      }
    },
    "org.kgrid.adapter.javascript.JavascriptAdapter" : {
      "status" : "UP",
      "details" : {
        "type" : "JAVASCRIPT",
        "created" : "2020-06-15T14:59:15.540257500Z"
      }
    },
    "org.kgrid.adapter.proxy.ProxyAdapter" : {
      "status" : "UP",
      "details" : {
        "type" : "PROXY",
        "created" : "2020-06-15T14:59:15.540257500Z"
      }
    },
    "ping" : {
      "status" : "UP"
    },
    "shelf" : {
      "status" : "UP",
      "details" : {
        "numberOfKOs" : 1,
        "kgrid.shelf.cdostore.url" : "shelf"
      }
    }
  }
}

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/v1.0/welcome

The Hello World KO will return the following

{
  "result": "Welcome to Knowledge Grid, Fred Flintstone",
  "info": {
    "ko": {
      "@id": "hello-world",
      "@type": "koio:KnowledgeObject",
      "identifier": "ark:/hello/world",
      "version": "v1.0",
      "title": "Hello world",
      "description": "An example of Knowledge Object",
      "keywords": [
        "Hello",
        "example"
      ],
      "hasServiceSpecification": "service.yaml",
      "hasDeploymentSpecification": "deployment.yaml",
      "hasPayload": "src/index.js",
      "@context": [
        "http://kgrid.org/koio/contexts/knowledgeobject.jsonld"
      ]
    },
    "inputs": {
      "name": "Fred Flintstone"
    }
  }
}

The hello world example object uses the embedded javascript runtime. There is also a remote javascript runtime service which is more powerful and is used for the hello proxy example.

To use the remote environment you must download and start up the remote javascript runtime environment project by running npm install -g @kgrid/noderuntime and running the command kgrid-node

Note the configuration options at the end of this page.

# Activator Configuration

There are several settings that you can control on the Activator.

Activator Knowledge Object Shelf Location

By default the activator will look for a shelf in jar execution directory but the location the shelf can be configured:

java -jar kgrid-activator-1.3.1.jar --kgrid.shelf.cdostore.url=filesystem:file:///data/myshelf

java -jar kgrid-activator-1.3.1.jar --kgrid.shelf.cdostore.url=filesystem:file:///c:/Users/me/myshelf

Activator Cross-Origin Resource Sharing (CORS) The Activator by default allows all origins access to the api. You can tighten that access via the cors.url parameter.

To change the origins allowed:

java -jar kgrid-activator-1.3.1.jar --cors.url=https://myservice.com

Activator Server Port

To change the port:

java -jar kgrid-activator-1.3.1.jar --server.port=9090

Activator Object Auto-Reload

By default the activator does not automatically reload objects but it can be configured to activate an object when it detects a change to a file on the shelf by setting this property:

java -jar kgrid-activator-1.3.1.jar --kgrid.activator.autoreload=true

Activator Manifest Loading

To have the activator start up with a collection of knowledge objects you can specify a manifest file with a list of knowledge object urls to be downloaded and unpacked at startup.

java -jar kgrid-activator-1.3.1.jar --kgrid.activator.manifest=file:/path/to/manifest or java -jar kgrid-activator-1.3.1.jar --kgrid.activator.manifest=http://path-to-manifest

For example a manifest file for the example collection would look like this:

{"manifest":[
  "https://github.com/kgrid-objects/example-collection/releases/download/2.0.0/99999-fk4n99hh99-v0.0.2.zip",
  "https://github.com/kgrid-objects/example-collection/releases/download/2.0.0/exec-example-v1.0.0.zip",
  "https://github.com/kgrid-objects/example-collection/releases/download/2.0.0/exec-step-v1.0.0.zip",
  "https://github.com/kgrid-objects/example-collection/releases/download/2.0.0/hello-world-v1.0.zip",
  "https://github.com/kgrid-objects/example-collection/releases/download/2.0.0/hello-world-v1.3.zip",
  "https://github.com/kgrid-objects/example-collection/releases/download/2.0.0/ri-bmicalc-v2.0.zip",
  "https://github.com/kgrid-objects/example-collection/releases/download/2.0.0/score-calc-v0.1.0.zip",
  "https://github.com/kgrid-objects/example-collection/releases/download/2.0.0/score-calc-v0.2.0.zip",
  "https://github.com/kgrid-objects/example-collection/releases/download/2.0.0/score-calc-v0.3.0.zip"
]}

# Running With External Runtime

The activator also has a proxy adapter which can connect to an external runtime and execute code natively in that environment. Currently we have created a reference implementation of a Node.js remote environment which can be used to execute JavaScript code. To use the KGrid Node.js runtime, here is the step-by-step instruction.

  1. Follow the same steps as above for downloading and starting up an activator.
  2. Download the javascript runtime by running npm install -g @kgrid/noderuntime
  3. Start the javascript runtime with the command kgrid-node Note: you may need to configuring the runtime, see below.
  4. Download the hello proxy object and unzip it in your shelf directory
  5. You can use the same commands as above for inspecting and running the object. For example:
curl -X POST -H "Content-Type:application/json"  \
    -d "{\"name\": \"Fred Flintstone\"}" \
     http://localhost:8080/hello/proxy/v1.0/welcome

returns

{
  "result": {
    "result": "Welcome to Knowledge Grid, Fred Flintstone",
    "request_id": "b75c5846-af22-499a-8547-2e9e1d85ea70"
  },
  "info": {
    "ko": {
      "@id": "hello-proxy",
      "@type": "koio:KnowledgeObject",
      "title": "the best hello world ever",
      "identifier": "ark:/hello/proxy",
      "version": "v1.0",
      "description": "A native node js object run through the proxy adapter with one artifact",
      "contributors": "Kgrid Team",
      "keywords": [
        "Hello",
        "example"
      ],
      "hasServiceSpecification": "service.yaml",
      "hasDeploymentSpecification": "deployment.yaml",
      "hasPayload": "src/index.js",
      "@context": [
        "http://kgrid.org/koio/contexts/knowledgeobject.jsonld"
      ]
    },
    "inputs": {
      "name": "Fred Flintstone"
    }
  }
}

# Configuring the Remote Runtime

These settings apply to the Node.js runtime environment communicating with the proxy adapter in the KGrid Activator. More details on the communication message format, please refer to the documentation of the activator and the proxy adapter.

Adapter Location

This property has to point to the adapter that the remote environment will register with and be used in

KGRID_ADAPTER_PROXY_URL = http://path-to-adapter

Self Location

This has to point to the public URL that can be used to access this runtime environment

ENVIRONMENT_SELF_URL = http://path-to-this-runtime

Last Updated: 7/8/2020, 5:29:32 PM