Skip to content
UserVoice integration for Pivotal
PHP
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
oauth
README
base.php
common.php
config.sample.php
hook.php
htaccess.sample
import.php
license.txt
stats.php
uservoice_http.class.php
uservoice_oauth.class.php

README

UserVoice-Pivotal v1.0


UserVoice-Pivotal is an Uservoice (http://uservoice.com) integration
script for Pivotal Tracker (http://www.pivotaltracker.com).


[ PREREQUISITES ]

* PHP5
* PHP/cURL


[ INSTALLATION ]

Just clone the repository into a directory on your web server and you're
almost ready to go :)

  cd ~/public_html/
  git clone git@github.com:blogpig/uservoice-pivotal.git
  cd uservoice-pivotal
  copy config.sample.php config.php


[ CONFIGURATION ]

Edit the "config.php" and enter your UserVoice info and credentials.

Here's a brief description of the settings you need to configure.

* USERVOICE_SUBDOMAIN

Your UserVoice subdomain, e.g. for 'http://yoursubdomain.uservoice.com',
enter just 'yoursubdomain' in this field.

* USERVOICE_KEY & USERVOICE_SECRET

On UserVoice Dashboard, go to Seetting > Channels and scroll down to the
API section. Click the 'Add API Client' button to create a new API
client. Copy the 'Key' and 'Secret' params and paste them into
USERVOICE_KEY and USERVOICE_SECRET.

* USERVOICE_ADMIN_EMAIL & USERVOICE_ADMIN_PASSWORD

Your email and password for logging into the UserVoice Admin area. You
can also create dedicated UserVoice Admin for Pivotal integration.

* USERVOICE_SITE_URL

This is by default your UserVoice site URL (e.g. 'http://yoursubdomain.uservoice.com'),
but can also be e.g. 'http://support.yourdomain.com' if you use a custom
Feedback Site (top of the Settings > Channels page).

* USERVOICE_IMPORT_FORUMS

Imports all forums by default ('all'), but can be configured to import
none ('none') or just a few (e.g. '12345,12678' will import suggetions
from forums with IDs 12345 and 12678 only).

Additional filtering can be configured by using category and/or forum 
params for Pivotal Import API URL (see PIVOTAL TRACKER CONFIGURATION below).

* USERVOICE_IMPORT_TICKETS

Again, imports all tickets by default ('all'), can be turned off ('none')
and can also be configured to import just tickets having a certain
custom field and value (e.g. 'Type=Bug' will import just tickets with
the value of custom field Type set to Bug)

Additionaly, if you want to add a dynamic filter for each Pivotal project
you can set it to e.g. 'Product=%product_name%' - this uses the URL param 
'product_name' and import just tickets having that value for custom field
'Product' (see PIVOTAL TRACKER CONFIGURATION below).

* USERVOICE_UPDATE_FORUMS & USERVOICE_UPDATE_TICKETS

Set these to 'all' if you want suggestion & ticket statuses in UserVoice
updated when story statuses are updated in Pivotal.

* LOG_ERRORS, LOG_IMPORTS & LOG_HOOKS

The script will write errors to the log file by default, but you can
enable both hook and import requst logging by setting the values of the
LOG_ERRORS, LOG_IMPORTS and LOG_HOOKS params.

Make sure the LOGS_PATH (e.g. public_html/uservoice-pivotal/logs/) is
writable by the web server.


[ SECURITY ]

In order to protect the import script, configure basic authentication
for the 'import.php' file. You can use the htaccess.sample file as a
template.

More info: http://www.howtoforge.com/htaccess_authentication


[ PIVOTAL TRACKER CONFIGURATION ]

Go the the Project Integrations page for your project.

* Activity Web Hook

Link the hook to the hook.php script on your site, e.g. 
http://yourdomain.com/uservoice-pivotal/hook.php

* External Tool Integrations

In the "Create New Integration" dropdown select "Other" and fill the
following params:

  Name: UserVoice
  Base URL: http://yourdomain.com/uservoice-pivotal/base.php/
  Import API URL: http://yourdomain.com/uservoice-pivotal/import.php

The import script also accepts a 'category' param if you want to filter
the suggestions being imported, e.g.

  http://yourdomain.com/uservoice-pivotal/import.php?category=YourProduct

Other supported params include 'forum' (expects the ID of your UserVoice 
forum) and any defined custom fields (see USERVOICE_IMPORT_FORUMS and 
USERVOICE_IMPORT_TICKETS above), e.g.

  http://yourdomain.com/uservoice-pivotal/import.php?forum=123456
  http://yourdomain.com/uservoice-pivotal/import.php?product_name=YourProduct

You will also want to protect your import script with basic auth:

  Basic Auth Username: [username from the .htaccess/.htpasswd file]
  Basic Auth Password: [password from the .htaccess/.htpasswd file]


[ CONCLUSION ]

That should be enough to get you going :) Comments & suggestions are
most welcome :)
Something went wrong with that request. Please try again.