Integration of issues addressed by jpklein

.gitignore

@@ -0,0 +1,3 @@
+scripts/config/*
+!scripts/config/default.config.php
+

README.md

@@ -1,32 +1,61 @@
 slack-integration
 =================
 
-A place where I put some integration scripts for the popular Slack messaging platform.
+Some integration scripts for the popular Slack messaging platform.
 
+## Features
 
-#Rally Bot
+### Rallybot Cron
+Periodically pushes notifications from Rally into our team's Slack channel. Notifications are sent whenever:
 
-We use this to query our Rally instance for defects, tasks and user stories. I have it configured to respond to a /rallyme slash command in Slack.
+1. a comment is added to a ticket
+2. a new defect, user story, or test case is created
+3. a user story changes state
 
-E.g.:
-/rallyme DE12345
-/rallyme US23456
-/rallyme TA34567
+The bot uses a combination of Rally's _state_ and _ready_ fields to track the progress of user stories. When a story's state is set to "In-Progress" and the ready field is checked, rallybot will announce that the story is ready for testing. When the QA team has completed testing, they may either: 1) uncheck the ready flag to have rallybot announce that the story needs work, or 2) set the story to "Completed" to notify the Product Owner that it is ready for acceptance.
 
-Each of these returns a nicely formatted summary of the defect, story or task, including the owner/submitter, creation date, story title, project and description. For documents that have attachments, such as uploaded screenshots, the summary will include a link to the first available attachment.
+> **Note**: Rally automatically sets a story's state to "Completed" when all of its tasks are completed, so be sure to leave at least one open task in order to correctly track stories with defects.
 
-#Image Bot / Gif Bot
+### Rallybot
+We use this to query our Rally instance for defects, tasks and user stories. It can be configured to respond to a Slack [slash command](https://slack.zendesk.com/hc/en-us/articles/201259356-Slash-Commands) or to any messages that start with a Rally ticket's formatted id, e.g.:
+```
+/rallyme DE12345
+/rallyme US23456 project
+TA34567 owner description
+```
+Entering the id of an artifact without any arguments returns a nicely formatted summary of the defect, story or task, including the owner/submitter, creation date, story title, project and description. For documents that have attachments, such as uploaded screenshots, the summary will include a link to the first available attachment. Otherwise, adding one or more field names after the id will filter the summary to just display the requested fields.
 
+### Image Bot / Gif Bot
 This one is simple. It uses the google image search JSON API to query for images that match a keyword. It is configured to use the Safe Search feature, since we use this tool in the workplace. Being able to add some levity to our work chats with amusing images from the internet makes life more fun.
-
-E.g.
+```
 /imageme kittens
 /gifme roflcopter
+```
 
+### XKCD Bot
+As geeks, we are well acquainted with the internet comic XKCD. This bot allows you to post an XKCD comic to the room, including the ALT text, which will be displayed beneath the image.
 
-#XKCD Bot
+E.g. `/xkcd 100` will return the "family circus" episode of XKCD.
 
-As geeks, we are well acquainted with the internet comic XKCD. This bot allows you to post an XKCD comic to the room, including the ALT text, which will be displayed beneath the image.
+## Installation
+
+1. Clone this repository to your server
+
+2. Create your config file from the default template:
+
+   ```
+   cd scripts/config
+   cp default.config.php config.php
+   ```
+
+3. Create a new incoming webhook in Slack
+
+   **Note**: Leave the channel to post to set to "#general", our scripts use channel-overrides to respond wherever the user issues a slash command.
+
+4. Edit your config file with the incoming webhook's unique webhook URL
+
+5. Add a slash command to Slack for each feature (for example: "When a user enters /rallyme, POST to http://example.com/rallyme.php")
+
+   **Note**: The scripts will respond to requests over POST or GET.
 
-E.g.
-/xkcd 100 will return the "family circus" episode of XKCD.
+6. If you are implementing Rally Bot, add your credentials to the config file

scripts/config/default.config.php

@@ -0,0 +1,35 @@
+<?php
+
+  ////////////////////
+ // Slack settings //
+////////////////////
+
+$SLACK_INCOMING_HOOK_URL = 'REPLACE ME'; //unique webhook URL including 'https://' and token value
+$SLACK_OUTGOING_HOOK_TOKEN = 'REPLACE ME'; //used to validate requests coming from Slack
+
+$SLACK_SUBDOMAIN = 'REPLACE ME'; //subdomain of slack.com used by your team, e.g.: 'cim'
+
+  ////////////////////
+ // Rally settings //
+////////////////////
+
+$RALLY_USERNAME = 'REPLACE ME';
+$RALLY_PASSWORD = 'REPLACE ME';
+
+$RALLYBOT_NAME = 'rallybot';
+$RALLYBOT_ICON = 'https://yt3.ggpht.com/-vkXOTHhRGck/AAAAAAAAAAI/AAAAAAAAAAA/IBjv0oYIm5Q/s100-c-k-no/photo.jpg';
+
+  ////////////////////////
+ // Rallycron settings //
+////////////////////////
+
+$RALLYCRON_PROJECT_ID = REPLACE_ME; //number after '#/' in URL of the rally project to track
+$RALLYCRON_CHANNEL = 'REPLACE ME'; //slack channel to post to; do not include hash symbol
+
+$CRON_INTERVAL = 61; //seconds between cron runs; pad for script run time and latency
+
+  //////////////////////
+ // Rallyme settings //
+//////////////////////
+
+$RALLYME_DISPLAY_VERSION = 2; //displays different fields for fetched artifacts

scripts/gifme.php

@@ -1,25 +1,23 @@
-<?
+<?php
 require('include/curl.php');
 require('include/slack.php');
-require('include/slack.config.php');
+require('config/config.php');
 
 $command = BuildSlashCommand($_REQUEST);
 
-$hook = $config['slack']['hook'];
-
 //use one or the other of $emoji or $iconurl
 $emoji = ":camera:";
 $iconurl = null;
 
 $enc = urlencode($command->Text);
 
-$imageSearchJson = get_url_contents('http://ajax.googleapis.com/ajax/services/search/images?v=1.0&safe=active&as_filetype=gif&rsz=8&imgsz=medium&q=animated+'.$enc);
+$imageSearchJson = get_url_contents('http://ajax.googleapis.com/ajax/services/search/images?v=1.0&safe=active&as_filetype=gif&rsz=8&imgsz=medium&q=animated+' . $enc);
 
 $imageresponse = json_decode($imageSearchJson);
 
-$userlink = "<https://cim.slack.com/team/{$command->UserName}|{$command->UserName}>";
+$userlink = '<https://' . $SLACK_SUBDOMAIN . '.slack.com/team/' . $command->UserName . '|' . $command->UserName . '>';
 
-if($imageresponse->responseData == null){
+if ($imageresponse->responseData == null) {
 	//{"responseData": null, "responseDetails": "qps rate exceeded", "responseStatus": 503}
 	$details = $imageresponse->responseDetails;
 	$status = $imageresponse->responseStatus;
@@ -29,12 +27,11 @@
 	die;
 }
 
-$whichImage = rand(0,7);
+$whichImage = rand(0, 7);
 $returnedimageurl = $imageresponse->responseData->results[$whichImage]->url;
 
 $payload = "@{$userlink} asked for '{$command->Text}'\n{$returnedimageurl}";
 
-$ret = slack_incoming_hook_post($hook, "gifbot", $command->ChannelName, $iconurl, $emoji, $payload);
-if($ret!="ok")
+$ret = slack_incoming_hook_post($SLACK_INCOMING_HOOK_URL, "gifbot", $command->ChannelName, $iconurl, $emoji, $payload);
+if ($ret != "ok")
 	print_r("@tdm, gifbot got this response when it tried to post to the incoming hook for /gifme.\n{$ret}");
-?>

scripts/imageme.php

@@ -1,60 +1,53 @@
-<?
+<?php
 require('include/curl.php');
 require('include/slack.php');
-require('include/slack.config.php');
+require('config/config.php');
 
 $command = BuildSlashCommand($_REQUEST);
 
-$hook = $config['slack']['hook'];
-
 //use one or the other of $emoji or $iconurl
 $emoji = ":camera:";
 $iconurl = null;
-$userlink = "<https://cim.slack.com/team/{$command->UserName}|{$command->UserName}>";
+$userlink = '<https://' . $SLACK_SUBDOMAIN . '.slack.com/team/' . $command->UserName . '|' . $command->UserName . '>';
 $maxtries = 2;
 $tries = 0;
 
-
 startover:
-    
+
 $imageresponse = RunImageSearch($command->Text);
 $tries++;
 
-if($imageresponse->responseData == null){
+if ($imageresponse->responseData == null) {
 	//{"responseData": null, "responseDetails": "qps rate exceeded", "responseStatus": 503}
 	$details = $imageresponse->responseDetails;
 	$status = $imageresponse->responseStatus;
-
-	if($status == 503 && $tries < $maxtries)
-	{
-	    sleep(1);
-	    goto startover; //yeah, it's a goto. deal with it. http://xkcd.com/292/
+
+	if ($status == 503 && $tries < $maxtries) {
+		sleep(1);
+		goto startover; //yeah, it's a goto. deal with it. http://xkcd.com/292/
 	}
-	
+
 	print_r("Sorry @{$userlink}, no image for you! [{$details}:{$status}]\n");
 	//print_r($imageresponse);
 	die;
 }
 
-$whichImage = rand(0,7);
+$whichImage = rand(0, 7);
 $returnedimageurl = $imageresponse->responseData->results[$whichImage]->url;
 
 $payload = "@{$userlink} asked for '{$command->Text}'\n{$returnedimageurl}";
 
-$ret = slack_incoming_hook_post($hook, "imagebot", $command->ChannelName, $iconurl, $emoji, $payload);
-if($ret!="ok")
+$ret = slack_incoming_hook_post($SLACK_INCOMING_HOOK_URL, "imagebot", $command->ChannelName, $iconurl, $emoji, $payload);
+if ($ret != "ok")
 	print_r("@tdm, gifbot got this response when it tried to post to the incoming hook for /imageme.\n{$ret}");
-
-
-
+
 function RunImageSearch($text)
 {
 	$enc = urlencode($text);
 
-    $imageSearchJson = get_url_contents('http://ajax.googleapis.com/ajax/services/search/images?v=1.0&safe=active&rsz=8&imgsz=medium&q='.$enc);
+	$imageSearchJson = get_url_contents('http://ajax.googleapis.com/ajax/services/search/images?v=1.0&safe=active&rsz=8&imgsz=medium&q=' . $enc);
+
+	$imageresponse = json_decode($imageSearchJson);
 
-    $imageresponse = json_decode($imageSearchJson);
-
-    return $imageresponse;
+	return $imageresponse;
 }
-?>

scripts/include/curl.php

@@ -1,30 +1,32 @@
-<?
+<?php
 //HTTP Utility Methods
 
-function get_url_contents($url) {
-    $crl = curl_init($url);
+function get_url_contents($url)
+{
+	$crl = curl_init($url);
 
-    curl_setopt($crl, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)');
-    curl_setopt($crl, CURLOPT_RETURNTRANSFER, 1);
-    curl_setopt($crl, CURLOPT_CONNECTTIMEOUT, 5);
+	curl_setopt($crl, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)');
+	curl_setopt($crl, CURLOPT_RETURNTRANSFER, 1);
+	curl_setopt($crl, CURLOPT_CONNECTTIMEOUT, 5);
 
-    $response = curl_exec($crl);
-    curl_close($crl);
-    return $response;
+	$response = curl_exec($crl);
+	curl_close($crl);
+	return $response;
 }
 
-function get_url_contents_with_basicauth($url, $username, $password) {
-    $crl = curl_init();
+function get_url_contents_with_basicauth($url, $username, $password)
+{
+	$crl = curl_init();
 
-    curl_setopt($crl, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)');
-    curl_setopt($crl, CURLOPT_URL, $url);
+	curl_setopt($crl, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)');
+	curl_setopt($crl, CURLOPT_URL, $url);
 	curl_setopt($crl, CURLOPT_USERPWD, "{$username}:{$password}");
-    curl_setopt($crl, CURLOPT_RETURNTRANSFER, 1);
-    curl_setopt($crl, CURLOPT_CONNECTTIMEOUT, 5);
+	curl_setopt($crl, CURLOPT_RETURNTRANSFER, 1);
+	curl_setopt($crl, CURLOPT_CONNECTTIMEOUT, 5);
 
-    $ret = curl_exec($crl);
-    curl_close($crl);
-    return $ret;
+	$ret = curl_exec($crl);
+	curl_close($crl);
+	return $ret;
 }
 
 function curl_post($uri, $data)
@@ -33,10 +35,11 @@ function curl_post($uri, $data)
 	curl_setopt($crl, CURLOPT_CUSTOMREQUEST, "POST");
 	curl_setopt($crl, CURLOPT_POSTFIELDS, $data);
 	curl_setopt($crl, CURLOPT_RETURNTRANSFER, true);
-	curl_setopt($crl, CURLOPT_HTTPHEADER, array('Content-Length: ' . strlen($data)));
+	curl_setopt($crl, CURLOPT_HTTPHEADER, array(
+		'Content-Length: ' . strlen($data)
+	));
 
 	$response = curl_exec($crl);
 	curl_close($crl);
 	return $response;
 }
-?>

scripts/include/googleimage.php

@@ -1,39 +1,36 @@
-<?
+<?php
 /*
 built based on the docs here:
 https://developers.google.com/image-search/v1/jsondevguide
 */
 
-
 function BuildSearchCommand($query, $size, $maxresults, $safe, $filetype)
 {
-    
-    $cmd = new stdClass();
-    $cmd->Size = $size;
-    $cmd->Query = $query;
-    $cmd->Count = $maxresults;
-    $cmd->Safe = $safe;
-    $cmd->FileType = $filetype;
-    
-    return $cmd;
+
+	$cmd = new stdClass();
+	$cmd->Size = $size;
+	$cmd->Query = $query;
+	$cmd->Count = $maxresults;
+	$cmd->Safe = $safe;
+	$cmd->FileType = $filetype;
+
+	return $cmd;
 }
 
 function GetImageSearchResponse($cmd)
 {
-
-    $googleImageSearch = "http://ajax.googleapis.com/ajax/services/search/images?v=1.0&safe={$cmd->Safe}&as_filetype={$cmd->FileType}&rsz={$cmd->Count}&imgsz={$cmd->Size}&q={$cmd->Query}";
 
-    $result = CallAPI($googleImageSearch);
+	$googleImageSearch = "http://ajax.googleapis.com/ajax/services/search/images?v=1.0&safe={$cmd->Safe}&as_filetype={$cmd->FileType}&rsz={$cmd->Count}&imgsz={$cmd->Size}&q={$cmd->Query}";
 
-    return $result;
+	$result = CallAPI($googleImageSearch);
+
+	return $result;
 }
 
 function GetRandomResultFromResponse($n, $result)
 {
-    $resultArray = $result->responseData->results;
-    $count = count($resultArray);
-    $item = rand(0,$count-1);
-    return $resultArray[$item];
+	$resultArray = $result->responseData->results;
+	$count = count($resultArray);
+	$item = rand(0, $count - 1);
+	return $resultArray[$item];
 }
-
-?>

scripts/include/log.php

@@ -1,11 +1,11 @@
-<?
+<?php
+
 function mylog($logfile, $payload)
 {
-    $fh = fopen($logfile,"ra+");
-    fwrite($fh,time()."\n");
-    fwrite($fh,$payload);
-    fwrite($fh,"\n____________________\n");
-    
-    fclose($fh);
+	$fh = fopen($logfile, "ra+");
+	fwrite($fh, time() . "\n");
+	fwrite($fh, $payload);
+	fwrite($fh, "\n____________________\n");
+
+	fclose($fh);
 }
-?>