1.8 and 1.9 SDK Documentation

For AnswerHub versions 1.8 and 1.9.

Getting Started

This guide will assist you with developing AnswerHub Themes and Plugins to enhance and extend the functionality of your AnswerHub installation. In this opening chapter, we’ll look at what AnswerHub is and how it works along with instructions for how to use this guide. Then, we’ll show you the tools you’ll need to develop your own Themes and Plugins and walk you through setting up your local development environment. Once everything is set up locally, we’ll get you up and running with our sample theme.

What is AnswerHub?

AnswerHub is a developer engagement and community platform. By combining our core set of features and plugin options, you can create a custom, world-class developer ecosystem.

You can make your AnswerHub installation look and feel exactly as you want by creating your own themes, add new features by writing a Plugin, or integrate it with other enterprise systems through the REST API.

To learn more about AnswerHub and its features, please visit: https://www.devada.com/answerhub/.

Introduction to Interacting with AnswerHub As A Developer

Developers can interact with their AnswerHub community by working with the REST APIs, Themes and Plugins. The REST API contains many endpoints to work with different features such as Questions, Answers, Topics, Users, and Groups in AnswerHub. To change the functionality of your software, you can work with plugins. Theme plugins are the most common type of plugin to modify the style and feel of the core feature of your AnswerHub community. To extend the core features of your AnswerHub community to change behavior and integrate with third-party applications, creating custom plugins would be the final more complex step to modifying your AnswerHub community.

We power AnswerHub by Java, Spring, Hibernate and FreeMarker with JQuery and CSS on the frontend. We use Hibernate for maintaining persistence and FreeMarker for templating.

You can reach additional details on endpoints, working with the REST API, working with the UI, new features, releases, the AnswerHub blog, and contacting support, through the main page of our documentation site.

Using this Guide

We design this guide for AnswerHub customers who want to customize their software either through a new look-and-feel (Theme) or additional functionality (Plugin). This is one of the most powerful features of AnswerHub: you can customize the user experience to fit your particular needs, which increases engagement in your developer community".

This guide assumes the user is familiar with the following:

Typographical Conventions

Convention

Explanation

Italics

Introduces new terms with which you may not be familiar.
Also used occasionally for emphasis.

Bold

Emphasizes important information. Also indicates button, menu, and icon names on which you can act. For example, click Next.

UPPERCASE

Indicates keys or key combinations you can use. For example, press the ENTER key.
Also used for SQL reserved words.

monospace

Indicates syntax examples, values that you specify, or results you receive.

monospaced italics

Indicates names that are placeholders for values you specify.

forward slash /

Separates menus and their associated commands. For example, Select File/Copy means you should select Copy from the File menu.
The slash also separates directory levels when specifying locations under UNIX.

angled brackets < >

Macros in FreeMarker as specified using this notation, combined with this @ or # symbol inside of < >. E.g. <@macro />

vertical rule |

Indicates an "OR" separator used to delineate items.

brackets [ ]

Indicates optional items. For example, in the following statement: SELECT [DISTINCT], DISTINCT is an optional keyword.
Also indicates sections of the Windows Registry.

braces { }

Indicates you must select one item. For example, {yes | no} means you must specify either yes or no.

ellipsis . . .

Indicates the immediately preceding item is repeatable any number of times in succession. An ellipsis following a closing bracket indicates all information in that unit is repeatable.

Contacting Support

For support and assistance with the AnswerHub SDK, please visit success.answerhub.com to check if anyone has already asked and answered your question. If your question doesn’t show up in the search, please post your question on the site and your Customer Success Manager will reach out to you as soon as possible.

Setting Up Your Local Development Environment

When developing themes, it is best to do it in an environment identical to the production server which will eventually host your AnswerHub installation. Your development environment can either be local or remote. Configuring a local environment to work on your AnswerHub theme or plugin is beneficial for several reasons:
• You can build your theme locally without relying on a remote server. This setup speeds up your development process and allows you to see changes instantly in your browser.
• You do not need an Internet connection to build your theme.
• You can test your theme from a variety of perspectives. This is important, especially if you plan
on releasing your theme to a larger audience and want to ensure maximum compatibility.

Installing from a Docker Container

AnswerHub deploys using Docker, a popular distribution mechanism for software that will enable you to run and configure the installation in the most expedient manner. This section will walk you through installing AnswerHub from a Docker Container.

Prerequisites

A fresh install of AnswerHub comes in a configured Docker container, which is perfect for running a proof of concept, or if you are looking for a local environment to develop some custom Plugins to customize your AnswerHub experience. If you are looking to deploy AnswerHub for a production installation, you will want to follow the instructions below on installing the pre-configured Docker container but will also want to install and use a separate MySQL installation on a separate machine.

To get started, ensure you have the 1.8 version of the OpenJDK and Docker installed on your local machine. If you already have Docker, make sure it is running. To expedite the process, we’ve included the links to the installers for those below:

  • Install Java v1.8: https://openjdk.java.net/install/
  • Install Docker: https://docs.docker.com/get-started/
    • Once you have Docker setup and running, you’ll need to increase the available memory that Docker has allocated to run all the software in the container. Click on the Moby icon at the top of your screen and select “Preferences/Advanced”. In this window, move the slider to give Docker 4GB of memory:

📘

NOTE:

If you will be installing a production AnswerHub Setup, we recommend you install MySQL 5.7 on a separate machine from the machine running AnswerHub. You can download MySQL 5.7 and set it up using the instructions here: https://dev.mysql.com/downloads/mysql/5.7.html.

Downloading the AnswerHub Binaries

You can download the AnswerHub package from our Artifactory system at https://dzone.jfrog.io/. If you do not yet have login credentials, please get those from your Customer Success Manager.

Once you have your credentials, navigate your browser to https://dzone.jfrog.io/ and click on the LOG IN button in the upper right corner of the screen. Once you log in, navigate to the Artifacts section using the menu bar on the left side of the screen as illustrated below:

In the Artifact Repository Browser, navigate to answerhub-release-local, open the drop-down and select the latest release (in this instance, it is 1.9). In that directory, you will find a tar.gz file. Click on it, then select the DOWNLOAD button to download to your local machine. Note, when you select the file, it will have the necessary checksums to validate the downloaded bits.

Installation and Service Setup

Now that we have the pieces we need to install AnswerHub, let’s get started. The first step will be to extract the answerhub*.tar.gz file you just downloaded from Artifactory. Choose the installation folder you’d like and extract the file in the location you want AnswerHub installed:
$ tar -zxvf answerhub-1.9.tar.gz

Once you have extracted the file, you’ll want to cd into the answerhub directory using the command below:
$ cd answerhub

Next, you will want to copy the original configuration properties inside conf/config.properties.dist, to share/config.properties using the command below:
$ cp conf/config.properties.dist share/conf/config.properties

Keeping the original config.properties.dist file allows you to back out any configuration changes by keeping a clean version in the conf/directory. At this point, there are two different ways to set up your installation:

  • Using MySQL inside the Docker container
  • Using a standalone MySQL running on a separate machine.
    Each step below will walk you through setting up either configuration.

Update Database Information in the config.properties file

Now that we have our config.properties file in the correct directory, we need to make some edits to that file before we can start the service through Docker. If you are using an external database, edit the answerhub/share/conf/config.properties file to contain your external database information in the ‘Database Config’ section. If you are using the embedded database, edit the answerhub/share/conf/config.properties file with your favorite text editor and update both the ‘Database Config’ section and the ‘Elastic Search Config’ section of the file to match the following:

#
# database config
#
#########################
database.engine=mysql
# mysql, mssql, postgresql
database.name=ahub
database.user=test
database.password=test
database.url=ahub-mysql
#########################
#
# elastic search config
#
########################
# uncomment when using embedded elastic search service with docker on premise
elastic.url=http://ahub-elastic:9200
#########################```
Additionally, since this is our first local install, we will set the configuration to automatically update the database through DDL commands.

To make this configuration change, make sure to uncomment the "ddl.auto.enabled=false" line and set the value from false to true when using any version of AnswerHub 1.8+. Your configuration should look like the following:

`ddl.auto.enabled=true`


If you are using the MySQL database in the Docker container, you must remove the README.md file from the **answerhub/share/db/mysql** directory to avoid errors on startup by using the command below:
`$ rm share/db/mysql/README.md`


[block:callout]
{
  "type": "info",
  "body": "If you are using a remote database (when your MySQL is running on a different machine) setup, use the **database.name, database.user, database.password, and database.url** that you have the MySQL instance configured for. You may need to contact your database administrator for the proper information.",
  "title": "NOTE:"
}
[/block]

## Setup the docker-compose.yml file
Now that we have the configuration file setup, we need to update the **docker-compose** file to match the setup we have decided to use. If you are using a MySQL database on a separate machine, you can skip this step. If not, you need to rename the existing **yml** file and move the **docker-compose** file that sets up the MySQL database to the proper name using the commands below:
`$ mv bin/docker-compose.yml bin/docker-compose.yml.orig`
`$ mv bin/docker-compose.yml.mysql bin/docker-compose.yml`

## Log in to Artifactory
Using your Artifactory credentials you used when downloading the **answerhub.tar.gz** file, **log in** through the terminal window using the command below:
```$ docker login dzone-answerhub-container.jfrog.io
Username: myLoginUID
Password:
Login Succeeded```


## Startup the Docker Container
Change directories to the **answerhub/bin** directory, then startup the Docker container using the following commands:
`$ cd bin`
`$ docker-compose up -d`


[block:callout]
{
  "type": "info",
  "body": "The -d flag on the docker-compose command runs the docker container in the background. For debugging and running in the foreground remove the -d flag. Congratulations! When the docker container starts up, you will be able to access the AnswerHub installation at http://localhost:80.",
  "title": "NOTE:"
}
[/block]

If you have issues or errors with your setup, please see [Appendix A - Troubleshooting AnswerHub Docker Startup](doc:appendix-a-troubleshooting-answerhub-docker-startup) in this guide.

Now that your AnswerHub installation is up and running, you may need to shut it down to modify and upload your plugins and themes. To stop the docker container on your machine, use the following command:
`$ docker-compose down`
To start the docker container again, use the same docker command we used earlier:
`$ docker-compose up`
**Don’t do that now though, you’ve got the service started, so it’s time to configure your installation!**


[block:api-header]
{
  "title": "Setup Your AnswerHub Instance"
}
[/block]

Now that the AnswerHub server is up and running, navigate your browser to http://localhost:80/ and you’ll see a screen like this:


[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/9b11764-TeamhubInstallationProcessStep1.png",
        "TeamhubInstallationProcessStep1.png",
        424,
        554,
        "#dcddd8"
      ]
    }
  ]
}
[/block]

You can change your Network Name and Site Name to something more descriptive, but do not change the Site Domain or Admin Domain for your local installation. You should only change these fields for cloud installations of AnswerHub.

Next, upload the license file you received from your Customer Success Manager by clicking on the **CHOOSE FILE* button.

Now click on **“SERVER ADMIN”** to proceed to step 2. You will see a screen like the one below, choose and type in your admin password and e-mail address for the Server Administrator. This admin user is the admin for the entire installation. Do not confuse it with a normal user that is an administrator for the individual site. Since AnswerHub installations can have multiple sites in a single installation, you will have one Server Admin and then individual admins for the different sites.


[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/c6edad4-TeamhubInstallationProcessStep2.png",
        "TeamhubInstallationProcessStep2.png",
        514,
        443,
        "#dadbd8"
      ]
    }
  ]
}
[/block]

Now that we have the Server Admin, we need to get the Administrator for the site setup. The next screen allows you to choose a username, password, and e-mail address for the AnswerHub site we’ll be using to build our themes and plugins with. Pick a username and password for your user and then click **“COMPLETE SETUP”**.


[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/5c19103-TeamhubInstallationProcessStep3.png",
        "TeamhubInstallationProcessStep3.png",
        483,
        406,
        "#d8d9d6"
      ]
    }
  ]
}
[/block]

Now that we have the setup complete, you’ll see the screen below. Click on **“VIEW SITE”**.


[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/7c612cf-TeamhubInstallationProcessComplete.png",
        "TeamhubInstallationProcessComplete.png",
        506,
        306,
        "#cccfca"
      ]
    }
  ]
}
[/block]

You will now see the default installation of AnswerHub as below:


[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/cf2b0cd-AnswerhubWelcomePage.png",
        "AnswerhubWelcomePage.png",
        704,
        622,
        "#eef0f2"
      ]
    }
  ]
}
[/block]

If you don’t see the page above after a few minutes and see the warming up page instead, refresh your browser.


[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/0350282-AnswerhubWarmingUp.png",
        "AnswerhubWarmingUp.png",
        974,
        531,
        "#f7f7f7"
      ]
    }
  ]
}
[/block]




[block:api-header]
{
  "title": "Enabling the REST API"
}
[/block]

To make API requests to AnswerHub, you must first enable **REST API**. After you enable the **REST API** in the site administration page, you must then give yourself the **USE API** permission.

To enable the AnswerHub REST API, follow these steps:
1. Log in to AnswerHub.
Log in to AnswerHub with a user who has *Administrator* permissions.
2. Navigate to your administration Dashboard.
Click on the **Avatar** icon at the top right of the AnswerHub page and select **Administration.**
**Result**: The **Dashboard** tab of the **AnswerHub Administrator Dashboard** displays.
3. Navigate to **Site > General.**
Under the **Site** section, select the **General** menu.
**Result**: A drop-down menu with **Settings, Navigation, Sitemaps, Custom Header/Footer** displays in the **General** menu.
4. Navigate to **Settings** in the **General** menu.
Under the **General** menu, select the **Settings** tab.
**Result**: A form with various fields and the **Site Privacy** and **REST API Status** panes should appear.
5. Enable the **REST API.**
Under the **REST API Status**, switch **REST API Status** to **Enabled.**
**Result**: A green bar appears confirming you enabled the REST API and that you must have the Use API permission to make API requests.


[block:api-header]
{
  "title": "Grant USE API Permission"
}
[/block]

To grant the Use API permission to an AnswerHub user, follow these steps:
1. Log in to AnswerHub.
Log in with a user who can access the **Administration** page. To log in as an administrator, enter your **username** and **password** and click **SIGN IN.**
2. Navigate to the administration dashboard.
Click on your **Avatar** icon at the top right of the AnswerHub page and select **Administration.**
**Result**: The **Dashboard** tab of the **AnswerHub Administrator Dashboard** displays.
3. Navigate to **Users & Groups** to manage users.
Select the **Manage** tab under the **Users and Groups** section.
**Result**: The **Users, Groups, Custom Roles** drop-down displays.
4. Choose one of two ways to find a user.
There are **two ways to find the user** to update their permissions.
a. Scroll through and find the user within the Users pane.
**Result**: The **Permissions: [User]** page displays.
Click the **Wrench** icon next to the user you wish to have the *Use API* permission and select **Permissions.**
b. Using the search field, you can start typing in the name you want and then select the user.
**Result**: You will arrive at the user account information section.
Click the **Wrench** icon and select **Edit Permissions.**
**Result**: The **Permissions: [User]** page displays.
5. Open Advanced Settings in Site Permissions.
Within the **Site Permissions** column, click the **Wrench** icon and select **Advanced.**
**Result**: The **Advanced Editor** displays with multiple role options.
6. Navigate to **Other Roles** in the **Advanced Editor.**
Within the **Advanced editor,** scroll down to the **Other Roles** section and in the **Status** drop-down menu, next to *Use API,* select **Grant**.
7. Enable the **USE API** permission
Click **OK.**
**Result**: The **USE API** permission should now display in green in the column you chose in step 6.


[block:api-header]
{
  "title": "Enabling Elastic Search in the Admin Console"
}
[/block]

Once you are in the Administrator Dashboard:
1. Navigate to **Site > Optimization > Manage Search.**
2. Select the **Settings** tab.
3. In the Server text field, replace **localhost **with **ahub-elastic.**
4. Click the **SAVE CHANGES** button.
5. Select the **Operations** tab and click the **REBUILD SEARCH INDEX** button.

Now you are ready to go to the theme guide to learn about the sample theme and theme basics.

 

What’s Next
Did this page help you?