This repository contains sample app demonstrating yellowant gem usage. This sample app is for sole purpose of introducing developers to YellowAnt API This repository contains a sample app demonstrating yellowant gem usage. This sample app is for sole purpose of introducing developers to YellowAnt API
YELLOWANT SAMPLE TODO APP
Sample Ruby on Rails application for creating a TODO List application for YellowAnt. For API documentation, please visit https://apidocs.yellowant.com
These instructions will get you started with building basic YellowAnt application.
Register this application with your YellowAnt Developer account
Once you have logged into YellowAnt, head over to your team's subdomain developer page, https://yourteamsubdomain.yellowant.com/developers/
Click on the button "Create New Application"
Fill the form and click on "Create Application": Display Name: A human readable display name for the application. Invoke Name: A simple single word which users can use to control this app. Short Description: A human readable short description
You need to create the 5 functions that are understood by this Django app.
- createitem(title, description): create a new todo item Title [varchar, required]: title of a todo item Description [varchar]: extra details of a todo item
- getlist(): get a list of todo items
- getitem(title): get a single todo item Title [varchar, required]: title of the todo item
- updateitem(oldtitle, newtitle, description): update a todo item Oldtitle [varchar, required]: id of the todo item Title [varchar]: new title of the todo item Description [varchar]: new description for the todo item
- deleteitem(title: varchar): delete a todo item Title [int, required]: id of the todo item
Example of how to create the function, createitem, which has two input arguments, title and description: 1. Click on "Add New Function". 2. Complete the form and click on "Create New Function": Display Name: Human readable name for this function. e.g. "Create a Todo Item" Invoke Name: A simple descriptive word for invoking this command. e.g. "createitem" Description: Description. e.g. "Add a new item to your todo list" Function Type: Set to "Command" Is Function Active: Set to "Yes" 3. After creating a new function, you're at the function overview page, scroll down to the section for input arguments, and click on "Add New Input Arg". 4. Add a new input argument, title, and click on "Save": Display Name: A simple description word for this argument. e.g. title Description: Describe the use for this argument. e.g. A title which summarizes this todo Type: The data type of this argument. e.g. varchar Required: Toggle it on. Input Example: A human readable example. e.g. Get Milk 4. Add a new input argument, description, and click on "Save": Display Name: A simple description word for this argument. e.g. description Description: Describe the use for this argument. e.g. Details about the todo item Type: The data type of this argument. e.g. varchar Required: Toggle it off. Input Example: A human readable example. e.g. Get nonskimmed milk from Krogers at 4th Cross St.
Getting started with application
This application helps you start with writing application code. When going to production, make sure you load all sensitive tokens and values through environment variables or encoded secrets for better security.
- Open solution in any text editor like Sublime Text. Make sure you have installed the gem 'yellowant'. Use gem install yellowant to install the required package. Also you might be required to execute a bundleinstall should the need arise and a warning displayed when the application is run. Open your terminal and run 'rails s' inside the directory that this repository is cloned into. The browser should open up stating errors present including the database name and credentials. Fix that to the ones present on your PC. The changes need to be made in the database.yml file.
- Copy ClientID, ClientSecret, Verifcation token from your Yellowant dashboard to relevant sections in app/controllers/home_controller.rb marked in <>. The database names stated in the databse.yml file will have to be manually created from your mysql terminal. Use your mysql password to autheticate.
- Start the development server running
rails son your teminal
- Open your browser with
- You will now be on the create integration page where in you can add accounts. Click on add account and provide authorization for yellowant.
Ngrok provides public URLs for your apps on local machine. You can use this to test out your application before launching it in production. Head over to Ngrok and create an account. Follow the instructions to set up ngrok on your machine. ngrok server by using
ngrok http 3000
After you start ngrok, note the link.
- You need to update your app Redirect URL and API URL in Yellowant dashboard. The correct URL extentions are present in the routes.rb file present in the config folder.
- Make sure the ClientID and Client Secret are correct and so is the Verification Token. Update them in the home_controller file.
Now you should be ready to communicate with Yellowant.
Using RTM Socket
In case your development server is behind a firewall, you can use Yellowant RTM Client to communicate.
- Enable RTM for your application on YellowAnt developer dashboard. Don't forget to click 'Update Application'
- Visit the YellowAnt RTM repo(https://github.com/yellowanthq/yellowantrtmclient) and follow instructions to run socket client on your machine.
- Go to Controllers/UserIntegrationController.cs, in "API" method, comment the lines under 'NOT using RTM' and uncomment the lines under "using RTM"
- Start your development server
Understanding Application Layout
This is an example application, to let you know basics of building an integration for YellowAnt. Don`t use this code for production. There are two main components to notice
- Controller (UserIntegrationController)
There are 3 controller functions red_yellowant, redirected and api_calls.
When you start a server go to
localhost:3000. This redirects you to the yellowant page using the client ID passed.
localhost:3000, click on 'Add Account'. This will redirect you to the redirected function where in your client ID is used to provide authentication with yellowant. In this controller, a user
state is created and redirect link to yellowant is constructed using state and clientID. Access tokens are generated in this process that allow access to yellowant API.
If user approves request, YellowAnt will redirect you to 'redirect url' you have mentioned in application dashboard. This controller handles this redirected request. Request comes with
state you created and a 'token'. You use these and complete OAuth cycle to get secret token form YellowAnt.
When user enters command in Slack/YellowAnt, that request is sent to 'API url' you mentioned in YellowAnt application dashboard. Those requests are handled by this controller. The API url is the name of the API function, here 'api_calls'.
All commands are executed directly under the api_calls function. If the commands get large its always better to use a seperate class to prevent confusion. Each command executed for this application is directly dependedent on the local database. The data JSON file has all data sent and recieved by across the API. We can recieve arguments with it and also the name of the function that has made the call.