btnexus-hook/doc/firstSetup.md

Baseline libary for blackout nexus hooks.

## set up Hook in the NexusUI
To use a Hook, it must be set up in the btNexus and trained into a `Knowledge Source`. The following steps have to be performed:
### Step 1: create Hook <a name="step1"></a>

To create the Hook you need to press `Create new Hook` under the menu `Management -> Development -> Hooks`
![where to click](DevHook.png)
You need to define a name for the new hook. After that you can click `create`(In a previous version there was a bug, that `create` was not clickable - just press Enter if this happens)

### Step 2: copy the Connect hash
Under `Management -> Development -> Hooks` every Hook has a connect hash. This hash must be copied to the .btnexurc file in the project which was created with the btNexus Workbench extension.

### Step 3: train an Intent for the Hook
To use the Hook in the test chat of a personality you need to train an Intent for the Hook. Therefore you need to create or edit a `Knowledge Source` under `Artificial Intelligence -> Knowledge Training` and create a new intent.
![where to click](newIntent.png)

Create a new `dialog branch` and set `Hook` as type for the `dialog branch`. In the dropdown choose the Hook created in [step 1](#step1) and click Save Hook.
![where to click](newBranch.png)
<!-- This migth change -->

Under `User Phrasings` you need to define examples of phrasings that should trigger the hook. If the branch is set up press `Save Hook`.
*Remember that your `personality` needs a minimum of 5 intents to be trainable., so you may need to create additional Intents, or obtain some from btMarket.*

### Step 4: Train your Personality
To test the Hook you need to train the `Knowledge Source` with your Hook to a personality. To do so, choose the `personality` under `Artificial Intelligence -> Personality Training` , add your `Knowledge Source` to the Personality's Knowledge, and start a new training.
![where to click](train.png)

### Step 5: Test your hook
To test your Hook you need to run `npm install` on your project and start the Hook with `node index.js`.
When the Hook is executing you can test it via the `Testchat` for your `personality`
(same place where you trained your personality)

## Implement functionality
To customize the empty example hook, that comes with setting up a new workspace for a Hook the following callbacks need to be implemented.