forked from GNUsocial/gnu-social
180 lines
6.0 KiB
Plaintext
180 lines
6.0 KiB
Plaintext
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.
|