diff --git a/lms/djangoapps/linkedin/README.rst b/lms/djangoapps/linkedin/README.rst new file mode 100644 index 0000000000..2c5490854a --- /dev/null +++ b/lms/djangoapps/linkedin/README.rst @@ -0,0 +1,121 @@ +============================ +LinkedIn Integration for edX +============================ + +This package provides a Django application for use with the edX platform which +allows users to post their earned certificates on their LinkedIn profiles. All +functionality is currently provided via a command line interface intended to be +used by a system administrator and called from other scripts. + +Basic Flow +---------- + +The basic flow is as follows: + +o A system administrator uses the 'linkedin_login' script to log in to LinkedIn + as a user with email lookup access in the People API. This provides an access + token that can be used by the 'linkedin_findusers' script to check for users + that have LinkedIn accounts. + +o A system administrator (or cron job, etc...) runs the 'linkedin_findusers' + script to query the LinkedIn People API, looking for users of edX which have + accounts on LinkedIn. + +o A system administrator (or cron job, etc...) runs the 'linkedin_mailusers' + script. This scripts finds all users with LinkedIn accounts who also have + certificates they've earned which they haven't already been emailed about. + Users are then emailed links to add their certificates to their LinkedIn + accounts. + +Configuration +------------- + +To use this application, first add it to your `INSTALLED_APPS` setting in your +environment config:: + + INSTALLED_APPS += ('linkedin',) + +You will then also need to provide a new key in your settings, `LINKEDIN_API`, +which is a dictionary:: + + LINKEDIN_API = { + # Needed for API calls + 'CLIENT_ID': "FJkdfj93kf93", + 'CLIENT_SECRET': "FJ93oldj939rkfj39", + 'REDIRECT_URI': "http://my.org.foo", + + # Needed to generate certificate links + 'COMPANY_NAME': 'Foo', + 'COMPANY_ID': "1234567", + + # Needed for sending emails + 'EMAIL_FROM': "The Team ", + 'EMAIL_WHITELIST': set(['fred@bedrock.gov', 'barney@bedrock.gov']) + } + +`CLIENT_ID`, `CLIENT_SECRET`, and `REDIRECT_URI` all come from your registration +with LinkedIn for API access. `CLIENT_ID` and `CLIENT_SECRET` will be provied +to you by LinkedIn. You will choose `REDIRECT_URI`, and it will be the URI +users are directed to after handling the authorization flow for logging into +LinkedIn and getting an access token. + +`COMPANY_NAME` is the name of the LinkedIn profile for the company issuing the +certificate, e.g. 'edX'. `COMPANY_ID` is the LinkedIn ID for the same profile. +This can be found in the URL for the company profile. For exampled, edX's +LinkedIn profile is found at the URL: http://www.linkedin.com/company/2746406 +and their `COMPANY_ID` is 2746406. + +`EMAIL_FROM` just sets the from address that is used for generated emails. + +`EMAIL_WHITELIST` is optional and intended for use in testing. If +`EMAIL_WHITELIST` is given, only users whose email is in the whitelest will get +notification emails. All others will be skipped. Do not provide this in +production. + +If you are adding this application to an already running instance of edX, you +will need to use the `syncdb` script to add the tables used by this application +to the database. + +Logging into LinkedIn +--------------------- + +The management script, `linkedin_login`, interactively guides a user to log into +LinkedIn and obtain an access token. The script generates an authorization URL, +asks the user go to that URL in their web browser and log in via LinkedIn's web +UI. When the user has done that, they will be redirected to the configured +location with an authorization token embedded in the query string of the URL. +This authorization token is good for only 30 seconds. Within 30 seconds the +user should copy and paste the URL they were directed to back into the command +line script, which will then obtain and store an access token. + +Access tokens are good for 60 days. There is currently no way to refresh an +access token without rerunning the `linkedin_login` script again. + +Finding Users +------------- + +Once you have logged in, the management script, `linkedin_findusers`, is used +to find out which users have LinkedIn accounts using LinkedIn's People API. By +default only users which have never been checked are checked. The `--recheck` +option can be provided to recheck all users, in case some users have joined +LinkedIn since the last time they were checked. + +LinkedIn has provided guidance on what limits we should follow in accessing +their API based on time of the day and day of the week. The script attempts to +enforce that. To override its enforcement, you can provide the `--force` flag. + +Send Emails +----------- + +Once you have found users, you can email them links for their earned +certificates using the `linkedin_mailusers` script. The script will only mail +any particular user once for any particular certificate they have earned. + +The emails come in two distinct flavors: triggered and grandfathered. Triggered +emails are the default. These comprise one email per earned certificate and are +intended for use when a user has recently earned a certificate, as will +generally be the case if this script is run regularly. + +The grandfathered from of the email can be sent by adding the `--grandfather` +flag and is intended to bring users up to speed with all of their earned +certificates at once when this feature is first added to edX.