Guidepost

Purpose

Your knowledge base is an incredibly important component of your company, providing value to your customers, employees, and other stakeholders! The purpose of this project is to help you gain more control over it.

Current Use Cases

• Back up your knowledge base to S3
• Import your knowledge base into your application
• Search your knowledge base with keywords

Table of Contents

• Prerequisites/Requirements
• Knowledge Base Providers
• Storage Services
• Installation
• Environment Variables
• Usage
• Contact
• Roadmap
• License

Prerequisites/Requirements

• Rails 4.2+
• Ruby 2.5+

Knowledge Base Providers

• Zendesk

Storage Services

• Amazon Simple Storage Service (Amazon S3)

Installation

Add this line to your application's Gemfile:

gem 'guidepost'

And then execute:

$ bundle

Environment Variables

Make sure to have certain environmental variables set, preferrably in your .bash_profile or in your .bashrc! The prefix of each environment variable needs to be the uppercased version of the name of your project that you will use to initialize your Guidepost::Provider (i.e. Zendesk in this case, since this is the only provider currently supported):

Zendesk

# The email associated with your Zendesk subdomain
ENV["#{YOUR_PROJECT_NAME}_GUIDEPOST_ZENDESK_EMAIL"]

# The password token associated with your Zendesk subdomain
ENV["#{YOUR_PROJECT_NAME}_GUIDEPOST_ZENDESK_PASSWORD_TOKEN"]

S3

# The access key associated with your AWS account
ENV["#{YOUR_PROJECT_NAME}_GUIDEPOST_AWS_ACCESS_KEY_ID"]

# The secret key associated with your AWS account
ENV["#{YOUR_PROJECT_NAME}_GUIDEPOST_AWS_SECRET_ACCESS_KEY"]

# The AWS region associated with this project
ENV["#{YOUR_PROJECT_NAME}_GUIDEPOST_AWS_REGION"]

# The name of the S3 bucket you want to upload your backups to
ENV["#{YOUR_PROJECT_NAME}_GUIDEPOST_S3_BUCKET_NAME"]

Usage

Back up your knowledge base to S3

Implement the backup functionality in your code

# The subdomain of your Zendesk account
subdomain = "spotify"

# The name you want to give to your project (name your environment variables accordingly)
project_name = "employee-portal"

zendesk = Guidepost::Provider::Zendesk.new(subdomain: subdomain, project_name: project_name)
zendesk.backup_all_articles(sideload: true)

Run a script outside of your codebase

$ rake zendesk_guide:backup_articles[spotify,employee-portal]

Import your knowledge base into your application

Generate all of the necessary model and migration files

$ rails g guidepost:models

Perform all of the schema migrations

$ rails g guidepost:migrate

Run a script outside of your codebase

$ rake zendesk_guide:import_guides_into_database[spotify,employee-portal]

Search your knowledge base with keywords

# The subdomain of your Zendesk account
subdomain = "spotify"

# The name you want to give to your project (name your environment variables accordingly)
project_name = "employee-portal"

# The keyword(s) you're searching for in articles
query = "analytics"

zendesk = Guidepost::Provider::Zendesk.new(subdomain: subdomain, project_name: project_name)
zendesk.search(query: query)

Contact

If you find and want to address any security issues with the project, email me! For anything else, like bug identifications or feature requests, feel free to file a Github issue or tweet me @srinitude.

Roadmap

• Tests
• More robust documentation
• More relevant use cases

License

Guidepost is released under the MIT License.