Sample dotnet 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.

1. Once you have logged into YellowAnt, head over to your team's subdomain developer page, https://your-team-subdomain.yellowant.com/developers/

2. Click on the button "Create New Application"

3. 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

4. After the application is created you will be at the application overview page. You need to update the application with more information and click on "Update Application".

   • API URL: The endpoint through which YellowAnt will communicate with this app.
   • Installation Website: The URL of your app where users will be able to begin integrating their YellowAnt accounts with this app.
   • Redirect URL: The endpoint at which YellowAnt will send the OAuth codes for user authentication.
   • Icon URL: A URI which points to an icon image for this app.
   • Creator Email: Your Email.
   • Privacy Policy URL: Any policy or TOC URL for your app.
   • Documentation URL: A documentation website URL for your app.
   • Is Application Active: set to "Active".
   • Is Application Production or Testing: set to "Production".
   • Application Visibility: set to "Public".

5. You need to create the 5 functions that are understood by this Django app.

   1. createitem(title, description): create a new todo item
      • title [varchar, required]: title of a todo item
      • description [varchar]: extra details of a todo item
   2. getlist(): get a list of todo items
   3. getitem(title): get a single todo item
      • title [varchar, required]: title of the todo item
   4. updateitem(old-title, new-title, description): update a todo item
      • old-title [varchar, required]: id of the todo item
      • new-title [varchar]: new title of the todo item
      • description [varchar]: new description for the todo item
   5. 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 non-skimmed milk from Krogers at 4th Cross St.

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.

1. Open solution in Visual Studio. Make sure you have installed YellowAntSDK from nuget package manager. Use Update-Package -Reinstall to install all references.
2. Copy ClientID, ClientSecret, Verifcation token from your Yellowant dashboard to relevant sections in Controllers/UserIntegrationController.cs
3. Start development server by clicking on Debug(your-default-browser) button or by striking (Ctrl + F5)
4. This will open a window in your browser with localhost:port
5. Note down the port number. you might need this to run ngrok and make your application available for testing on production

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 --host-header localhost:<port-your-servers-running-on> http <port-your-servers-running-on>

<port-your-servers-running-on> is the same port from above.

After you start ngrok, note the link.

1. You need to update your app Redirect URL and API URL in Yellowant dashboard.
2. Update Redirect URI in Controller/UserIntegrationController.
3. Make sure the ClientID and Secret are correct and so is the Verification Token

Now you should be ready to communicate with Yellowant.

In case your development server is behind a firewall, you can use Yellowant RTM Client to communicate.

1. Enable RTM for your application on YellowAnt developer dashboard. Don't forget to click 'Update Application'
2. Visit the YellowAnt RTM repo(https://github.com/yellowanthq/yellowant-rtm-client) and follow instructions to run socket client on your machine.
3. Go to Controllers/UserIntegrationController.cs, in "API" method, comment the lines under 'NOT using RTM' and uncomment the lines under "using RTM"
4. Start your development server

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

1. Controller (UserIntegrationController)
2. CommandCenter

There are 4 controller functions Integrate, NewIntegration, Oauthredirect, and API.

When you start a server go to <localhost:port>. If you are not logged in/signed up, this will redirect you to login/signup page. This is handled by Integrate controller.

Once on localhost:port, click on 'Add Account'. This will redirect you to /userintegration/newintegration. In this controller, a user state is created and redirect link to yellowant is constructed using state and clientID.

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 in 'NewIntegration' 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'.

The commandcenter has the commands file, buttons and a list of sample commands already made for this todo application. Each function is written as a seperate C# class for clarity.

The HelloYellowAnt class, elps with understanding the possible outputs from yellowant. Each of the other classes, namely Createitem, getItem, updateitem, GetList,DeleteItem and specific functions that perform the required activity

This is the root command class which controls the function calls that are made. Within the switch case, every command's invoke name is tested and the matching command's class is redirected to.