Osiris/Developer/ConversationScript

From Ori Wiki
Revision as of 12:42, 2 January 2018 by Shane7218 (talk | contribs) (Created page with "=Conversation Scripts Tutorial= ==Introduction== Osiris conversation scripts are created to provide a response to a users query. This page will detail how to create conversati...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Conversation Scripts Tutorial

Introduction

Osiris conversation scripts are created to provide a response to a users query. This page will detail how to create conversation scripts, register them on the Osiris service, and link them to a node in your applications node network.

Please note that you should first register an organisation and application within the Orion Identity Management System before continuing with this tutorial. Click here to find out how

You should also have added the registered application to Osiris. If you have not done so please click here before continuing .

Creating an Orion application system account

Before we begin talking about writing conversation scripts we need to create a system account for the application your creating scripts for in Orion. By this point you should have created an Organisation in Orion, registered an application, and registered that application on the Osiris site.

To create the system account follow the below steps:

  1. Visit your application manager page on Orion here http://orion.shanecraven.com/Management/ApplicationOverview (You should be logged in with your Orion account)
  2. In the Current Orion Applications section select the manage option under the application your planning to write conversation scripts for.
  3. Click the Create System Account option on the manage application page.
  4. The system account should now be created, click View Active System Accounts to see your new system account.
  5. You should be presented with a Public key and Secret key as well as options for the system account. Take note of the public and secret key at this point as you will need them later.
  6. Next select the Grant Permission option, which should open the permission grant dialog. Enter "iui" without the quotes and press Find Application.
  7. You should now be presented with a permission page for Osiris. Please read over this and select Grant Permission at the bottom of the page to continue.
  8. Your system account is now ready for use with Osiris :)

Conversation Router

The first step in writing Osiris conversation scripts is to download the Osiris Conversation Router to your local machine. The conversation router is a JAR file that targets java runtime version 1.8 so please ensure your java installation is up to date on the client machine.

The conversation router requires a config file which is different depending on how you plan on storing your conversation scripts. To make this tutorial easier a pre-built template is available to get started.

Storing scripts on Amazon S3

  1. Download the S3 config template.
  2. Edit the template as follows:
    1. Replace "aws_public_key" with the public key of the IAM account linked to your AWS account where the S3 repository is located.
    2. Replace "aws_secret_key" with the secret key of the IAM account linked to your AWS account where the S3 repository is located.
    3. Replace "s3_bucket_name" with the name of the bucket in your S3 account that your conversation scripts will be stored.
    4. Replace "system_account_public_key" with the public key of the system account we created earlier in this tutorial.
    5. Replace "system_account_secret_key" with the secret key of the system account we created earlier in this tutorial.
  3. Save your changes

Storing scripts on the Local Machine

  1. Download the local provider config template.
  2. Edit the template as follows:
    1. Replace "C:/PATH/TO/LOCAL/REPO" with a path to a folder on your local machine that will contain conversation scripts that you write.
    2. Replace "system_account_public_key" with the public key of the system account we created earlier in this tutorial.
    3. Replace "system_account_secret_key" with the secret key of the system account we created earlier in this tutorial.
  3. Save changes

Now that you have created your config file save it in the same directory as your conversation router jar file. Open a terminal window and use the cd command to reach the directory the OsirisConversationRouter.jar and config file are located. Your should then use the following command java -jar OsirisConversationRouter.jar -config <your_config_name> replacing <your_config_name> with the name of your config file (If your using the S3 template above this is config_s3.json, if using the local template this is config_local.json.

The conversation router should now start, if you following the instructions correctly you should see the message "Conversation Processing has started, router is go, awaiting traffic from the Osiris Conversation Network" within a minute after executing the above command. If you see this message you have successfully set up your conversation router. You can now kill the conversation router process for the moment as we wont need it for a while.

Writing Scripts

The next step in this tutorial is the writing of a conversation script. Conversation scripts can be written in both C# and java. Sample scripts are available for both languages below which you can use to complete this tutorial.

C#

  1. Create a compressed ZIP file on your machine, for the purposes of this demo call the file "demo.zip".
  2. Download the C# example
  3. Open the solution in Visual Studio 2015 (NOTE: You must have .NET 4.6 installed on your machine)
  4. Rebuild the project to restore missing nuget packages(Conversation scripts depend on the OsirisWindows nuget package. If rebuilding the project does not fix the missing packages issue, right click on your solution in Visual Studio and select Restore Nuget Packages.)
  5. Build your project
  6. If you now go to the bin directory of the project your should see the debug folder. Copy all the inner contents of this folder into the root of the zip file created in step one.
  7. You have now created and packaged your conversation script :)

Java

  1. Instructions coming soon.....

Now that we have created and packaged our conversation script the next step is putting the script into a script repository. The script repository will be different depending on the provider you chose earlier in this tutorial. For example if you chose to store your conversation scripts in S3 then you need to upload the "demo.zip" to the S3 bucket you specified in the config file earlier. If you chose to store the script on the local machine then you need to place the "demo.zip" file in the directory you specified as the localProviderRoot in the config.

Register Script

Now that you have created and packaged your first conversation script you need to register the script on the Osiris site.

  1. Visit the Osiris Developer Portal
  2. Select the edit option under the application you want to add the script for.
  3. Select the Launch Script Manager option on the Osiris Application Editor page.
  4. Select the Add New script option. Fill in the following information:
    1. For Name, enter "Demo example"
    2. For Language, select the language you chose in the writing scripts section.
    3. For TargetPlatform, choose the platform your local machine uses.
  5. Press Create Script.
  6. You should now see your script named "Demo Example" in the Existing Scripts section. Take note of the Script ID as you will need this later. Select the Manage Builder option.
  7. Select the Add New Build option. Fill in the following information:
    1. For version, enter "1.0" since this is the first build of our script.
    2. For CommandLine, you must enter the command the router should execute to access your script. For example if you chose to write your script in C# you should enter the name of the exe (CSharpScriptDemo.exe). If you chose to write your script in java then you should enter the name of the executable JAR (JavaScriptDemo.jar).
    3. For Path, you enter the name of the zip file you packaged the script in. For this tutorial you would enter demo.zip
    4. For ScriptProvider, you should choose based on how you stored your scripts. (Amazon S3 if storing yours scripts in S3, Local File System if storing your scripts on the local machine)
    5. Press Create Build
  8. Now our build should have been created. Select Manage Builds of the demo script once again.
  9. Select Make this build active on the build we just created. You have now registered your first Conversation Script with Osiris :)

Now that we have registered our script and created a build we are ready to connect it to a node.

Link with node

To link your new conversation script with a node in your node network do the following:

  1. Visit the Osiris Developer Portal
  2. Select the edit option under the application you added the script to previously.
  3. Select Launch Node Network Builder.
  4. You are now in the node network builder. This tool allows you to architect conversations in Osiris. For the purposes of this demo we are going to create two simple nodes to test our script. Select the Create Node option.
  5. Select Entry Node in the drop down. Fill in the following.
    1. Name: simply enter demo entry node.
    2. Description: again simply enter demo entry node.
    3. Expected Input: The expected input is what we expect the user to say to trigger the node. For the purposes of this demo we are going to put "testing123" without the quotes.
    4. Example User Input: Same as the expected input in this case. The user of your application will see this example.
    5. Acceptance Threshold: This expects a value from 0 to 100 representing how close a match the input from the user should be to that of the expected input. For the purposes of this demo we want 100.
    6. Learning Threshold: The learning threshold should always be lower then the acceptance threshold. If the users input is above the learning threshold but less then the acceptance it will prompt the user with a did you mean command. For the purposes of this demo input 90
    7. Show In Example: This checkbox specifies if we want users to be able to see this node in example, for this demo we do so tick the box.
    8. Start Node: A start node is the entry point into a conversation. Since this is the first node we want to set it as an entry node. Tick the checkbox.
    9. Press Save Changes.

Once the page has reloaded select the View Node Network Visualization option. You should see your newly created node. Nodes in the visualizer are color coded. Entry nodes are green, Static action nodes are yellow, Dynamic action nodes are red and conversation scripts are blue.

Now we need to create a dynamic action node. A dynamic action node is connected to a conversation script. We will then connect our entry node to our new dynamic action node and we will have a fully working conversation.

  1. Select the Create Node option.
  2. Select Dynamic Action Node from the dropdown box. Enter the following information.
    1. Name: simply enter demo action node.
    2. Description: again simply enter demo action node.
    3. Loading Message: The loading message is spoken by Osiris once the node is triggered. For this demo enter "Sure Thing!" without the quotes.
    4. Include Start Nodes: This option allows you to include start nodes upon completion of the node. In other words once the node has finished the next stage in the conversation can include entry nodes that are marked as start of node trees. For this demo we want this feature so tick the checkbox.
    5. Press save changes

Once the page reloads select the View Node Network Visualization option. We should now see our entry node (Green) and dynamic action node (Red) in the visualization. We now need to join them.

  1. Select the Create Node Connection option at the bottom of the visualization.
  2. Double click on the green node, the Source ID should now have information in it.
  3. Double click on the red node, the Destination ID should now have information in it. Please take note of the ID thats currently in the Destination ID section. You will need this in a moment.
  4. Press establish connection.

Now our nodes are joined, next we need to attach the script to our dynamic action.

  1. Select the Attach Script option at the bottom of the visualization.
  2. Node ID: Enter the ID of the action node that we took note of when connecting the nodes together. If you dont have this ID you can find it in the Existing Action Nodes section on the page.
  3. Script ID: Enter the script ID we took note of earlier when registering our script with the service. If you dont have this ID you can find it in the script manager.
  4. Select Establish connection.

We have now linked our script to out node network. Next we are going to test our script!

Test your new script

First you need to start the conversation router on your local machine, using the command we discussed earlier. Once you see the "Conversation Processing has started, router is go, awaiting traffic from the Osiris Conversation Network" message the router is activated.

Before we can actually use our application in Osiris we need to subscribe to it. We subscribe to applications in the application store. If you haven't previously subscribed to your application follow the below steps otherwise skip them.

  1. Go to the Application Store
  2. Click the subscribe button under your application, and grant permission if requested.

Next we need to visit the Conversation Portal, and select your application in the drop down list. Then press start conversation!

We are now in a conversation with Osiris. There are a number of options available to users on this page. If you select the "What Can I say ?" option you should see the entry node we created earlier in the example. "Enable Osiris Voice" allows you to issues commands with your voice. Simply say "osiris" followed by your command.

In the text box type "testing123" without the quotes. Before pressing send pay attention to your terminal window where your conversation router is running. Press Send. Osiris should then say "Sure thing" since that was the loading dialogue we set for that node. The router should now receive the request and execute your script. The you tube video we set in the script should appear in the browser shortly as will the response.

Congratulations you have successfully created, registered and tested your first conversation script :)

If you have any further questions please feel free to contact me.

Extras

C#

NuGet packages for Orion and Osiris C# libraries are now available.