Resource Library

Jargon Support, Concepts, Documentation, and More

Need Additional Support?

We're here for you and happy to answer questions. Don't hesitate to reach out!

Contact Support

Using Jargon with Rasa

Jargon’s content serving platform directly supports the Rasa NLG protocol, so your Rasa application can use Jargon to host and serve its content with just a few small configuration changes. The following steps will get you up and running in just a few minutes.


Step 1 - Sign up for Jargon

If you haven’t already, log into the platform to create a new Jargon account. You can use your existing Google, Github, or Amazon account to get started. If you prefer to use an email address and password click the “Sign Up” link at the bottom.


Step 2 - Create a new project

  1. Click “Create project” to start
  2. Give your new project a name (which you can change at any time) and click “Add Platforms and Locales”
  3. Click “Add Platform” and select “Rasa”
  4. Click “Add Locale” and select a locale for your project. Don’t see the right choice? Please let us know at support@jargon.com, and pick any option, such as “English (US)”. It’s OK if this locale doesn’t match the language your content is in, but you will need to use the value selected here in step 5 when configuring your Rasa application to talk to Jargon.
  5. Optional: import the “domain.yml” file from an existing Rasa application by dragging and dropping it only the box at the bottom of the dialog, or click “click to browse” and select the desired domain file
  6. Click “Add Team Member”
  7. If you wish you can invite other people to join your new Jargon project:

    a. Add their email address
    b. Select “admin” if they should be able to modify the project, or “readonly” if they only should be able to view the content
    c. Click “Add”
    d. When you’re done click “Create Project”

You can edit all project settings, including name, platforms, locales, and team members, on the “Settings” page after creating your project -- nothing is set in stone.


Step 3 - Use the studio to author your content

After creating your project you’ll be on the “project home screen”, which gives you an overview of the project. Select the “Studio” link to start authoring the content for your project. If you started with an existing Rasa domain file the studio will contain your imported responses -- you’ll see those in the “App Content” section on the left side of the screen. Also, please be aware that if you imported a lot of content into your project it may take some time for the studio to load -- we’re working hard on speeding that up!


Jargon’s content model mirrors Rasa’s:

  • A “response” contains the content that your application requests. While Jargon allows you to organize content into folders, for a Rasa application you should keep all of your responses at the top level, and give them a name starting with “utter_”
  • Each response has one or more variants. When multiple variants are eligible for a request the Jargon content server will pick one at random (just like multiple variants in a Rasa domain file). We’re currently working on conditional variants, which will support having a variant for a specific Rasa channel
  • Each variant can have multiple components:

    - Text
    - Image
    - Buttons
    - Custom elements. Note for custom elements the data is in JSON format, not YAML.

To create a response click the “+” button next to “Responses” on the left side of the screen. Beyond the response name, everything in this dialog (description, variant name, initial components) is optional.


Editing content

  1. Select a response (or create a new one) using the “App Content” section on the left of the screen
  2. Select the component (such as “Text”) in the center section of the screen that you want to edit. You can also add more components or create additional variants in this menu
  3. After selecting a component the appropriate editor will display. Many editors contain tools for using Jargon items such as snippets or variables (see here)
  4. To switch to a different component, select the down arrow that’s above the editor, towards the right of the screen

Committing changes

Under the covers Jargon uses a version control system to store your content. When you first edit content your changes are only visible to you. To deploy those changes to your application, and to make them visible to the other people invited to the project, click “Commit My Changes” in the top toolbar. You can add an optional message describing your changes.


Getting changes made by others

Use the “Get Latest” button to incorporate changes that other people on the project have committed. Note that if you’re behind on changes you need to click “Get Latest” before you can commit your changes.


Step 4 - Generate and deploy a release

A Jargon release takes the committed content for a project, validates that it doesn’t contain any errors, and converts it into a “content package” that’s usable in applications. To create a release:

  1. Select “Releases” on the top navigation bar
  2. Click the “Create Release” button
  3. Select the platforms and locales the release is for. This allows you to skip things that may not be ready yet
  4. You’ll see a progress indicator while the release is building; this will update automatically when the build finishes
  5. If your project contains any errors the build will fail. Click “Show info” for details on what needs fixing

A successful release will have a number of pieces of information that you’ll need to configure your Rasa application. Click “Show info” to view:

  • The Jargon Project ID
  • The “Content Interface ID”. This ID changes whenever the structure of your content (that is, the names of the responses your application can request, and the set of variables for each response) changes. It’s used to ensure that the Jargon content servers return content that’s compatible with your application.
  • The deployment status of the application, and any associated tags

Once a release has successfully built you can deploy it to Jargon’s content servers:

  1. For the release you want to deploy, click the up arrow in the “Deployment” column on the right side
  2. You can optionally add one or more “Tags” to identify the environment(s) the content is for. Tags allow you to first have content accessible to a development or staging environment, and later promote that content to a production environment. Note that you can add new tags to a deployment, but it’s not possible to remove a tag once added. To add a tag type in the desired name and click the “+” to the right of the input field
  3. Once you’ve added any desired tags click “Create” to create the deployment. Within a few moments Jargon’s content servers will load the new content and have it ready to serve.

Step 5 - Configure your Rasa application to talk to a Jargon content server

Add the following section to the “endpoints.yml” file for your application, replacing the content surrounded by “<>”

nlg:
url:
headers:
x-jargon-project:
x-jargon-contentinterface:
x-jargon-locale:
x-jargon-tag:

Content Server URLs

Choose the location that’s closest to where your application is running. Please contact support@jargon.com if you’d like us to add other locations.

  • Virginia, USA: https://cs-aws-us-east-1.jargoncontent.net/rasa/nlg
  • Dublin, Ireland: https://cs-aws-eu-west-1.jargoncontent.net/rasa/nlg
  • Tokyo, Japan: https://cs-aws-ap-northeast-1.jargoncontent.net/rasa/nlg

Deployment values

You can find the Project ID and Content Interface ID in the details for your deployed release. The tag value must match one of the tags associated with the release. The locale value must match one of the locales included in the release.


Example configuration

nlg:
url: https://cs-aws-us-east-1.jargoncontent.net/rasa/nlg
headers:
x-jargon-project: JP12345
x-jargon-contentinterface: JI12345
x-jargon-locale: en-US
x-jargon-tag: production


Step 6 - Launch your Rasa application

When launching your Rasa application (via “rasa run” or “rasa shell”) you’ll need include the following arguments:

--enable-api --endpoints endpoints.yml

Without these arguments Rasa core won’t use the configuration to talk to Jargon’s content servers.


Need additional support?

support@jargon.com