123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180 |
- 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
- 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
- that have already been imported
- php plugins/YammerImport/scripts/yammer-import.php
- 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.
|