gnu-social/plugins/YammerImport/README

Yammer Import Plugin
====================

This plugin allows a one-time import pulling user accounts, groups, and
public messages from an existing Yammer instance, using Yammer's public API.

Requirements
------------

* An account on the Yammer network you wish to import from
* An administrator account on the target StatusNet instance, or
  command-line administrative access
* This YammerImport plugin enabled on your StatusNet instance


Limitations
-----------

Yammer API key registrations only work for your own network unless you make
arrangements for a 'trusted app' key, so for now users will need to register
the app themselves. There is a helper in the admin panel for this.

In theory any number of users, groups, and messages should be supported, but
it hasn't been fully tested on non-trivial-sized sites.

No provision has yet been made for dealing with conflicting usernames or
group names, or names which are not considered valid by StatusNet. Errors
are possible.

Running via the web admin interface requires having queueing enabled, and is
fairly likely to have problems with the application key registration step in
a small installation at this time.


Web setup
---------

The import process is runnable through an administration panel on your
StatusNet site. The user interface is still a bit flaky, however, and if
errors occur during import the process may stop with no way to restart it
visible.

The admin interface will probably kinda blow up if JS/AJAX isn't working.

You'll be prompted to register the application and authenticate into Yammer,
after which a progress screen will display.

Two big warnings:
* The progress display does not currently auto-refresh.
* If anything fails once actual import has begun, it'll just keep showing
  the current state. You won't see an error message, and there's no way
  to reset or restart from the web UI yet.

You can continue or reset the import state using the command-line script.


CLI setup
---------

You'll need to register an application consumer key to allow the importer
to connect to your Yammer network; this requires logging into Yammer:

  https://www.yammer.com/client_applications/new

Check all the 'read' options; no 'write' options are required, but Yammer
seems to end up setting them anyway.

You can set the resulting keys directly in config.php:

    $config['yammer']['consumer_key'] = '#####';
    $config['yammer']['consumer_secret'] = '##########';

Initiate authentication by starting up the importer script:

    php plugins/YammerImport/scripts/yammer-import.php

Since you haven't yet authenticated, this will request an auth token and
give you a URL to open in your web browser. Once logged in and authorized
there, you'll be given a confirmation code. Pass this back:

    php plugins/YammerImport/scripts/yammer-import.php --verify=####

If all is well, the import process will begin and run through the end.

In case of error or manual abort, you should be able to continue the
import from where you left off by running the script again:

    php plugins/YammerImport/scripts/yammer-import.php

To reset the Yammer import state -- without removing any of the items
that have already been imported -- you can pass the --reset option:

    php plugins/YammerImport/scripts/yammer-import.php --reset

This'll let you start over from the requesting-authentication stage.
Any users, groups, or notices that have already been imported will be
retained.


Subscriptions and group memberships
-----------------------------------

Yammer's API does not expose user/tag subscriptions or group memberships
except for the authenticating user. As a result, users will need to re-join
groups and re-follow their fellow users after the import.

(This limitation may be lifted in future for sites on the Silver or Gold
plans where the import is done by a verified admin, as it should be possible
to fetch the information for each user via the admin account.)


Authentication
--------------

Account passwords cannot be retrieved, but the primary e-mail address is
retained so users can reset their passwords by mail if you're not using a
custom authentication system like LDAP.


Private messages and groups
---------------------------

At this time, only public messages are imported; private direct and group
messages are ignored. (This may change with Silver and Gold plans in future.)

Yammer groups may be either public or private. Groups in StatusNet currently
have no privacy option, so any private groups will become public groups in the
imported site.


Attachments
-----------

Attached image and document files will be copied in as if they had been
uploaded to the StatusNet site. Currently images do not display inline like
they do on Yammer; they will be linked instead.

File type and size limitations on attachments will be applied, so beware some
attachments may not make it through.


Code structure
==============

Standalone classes
------------------

YammerRunner: encapsulates the iterative process of retrieving the various users,
              groups, and messages via SNYammerClient and saving them locally
              via YammerImporter.

SNYammerClient: encapsulates HTTP+OAuth interface to Yammer API, returns data
                 as straight decoded JSON object trees.

YammerImporter: encapsulates logic to pull information from the returned API data
                and convert them to native StatusNet users, groups, and messages.

Web UI actions
-------------

YammeradminpanelAction: web panel for site administrator to initiate and monitor
                        the import process.

Command-line scripts
--------------------

yammer-import.php: CLI script to start a Yammer import run in one go.

Database objects
----------------

Yammer_state: data object storing YammerRunner's state between iterations.

Yammer_notice_stub: data object for temporary storage of fetched Yammer messages
                    between fetching them (reverse chron order) and saving them
                    to local messages (forward chron order).
Yammer_user,
Yammer_group,
Yammer_notice: data objects mapping original Yammer item IDs to their local copies.