- Create a new user account
- Update / upgrade / archive account
- Login as and display given Annotate page
- Logout via API
- Set user preferences
- Set email notifications
- Get account details
- List user accounts
- List user's activity log
- Delete user account
Create a new user account
The createAccount.php call allows you to create a user account. The request must be signed by the api-user (see Authentication). Accounts are initially created as 'standard' users - to allow the user to create workspaces, see the next section.
http://yoursite.com/annotate/php/createAccount.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user's account
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&sig=jill # The user's signature
&tagsfile=inittags # (optional) init user tags from php/inittags.txt
&firstname=Jill # (optional) To set full name,
&lastname=Jones # (optional) set these fields
The return value is either "OK" or "ERR {error message}".
Setting the initial set of available note tags: The optional tagsfile parameter can be set to load initial note tags from a file tagsfile.txt in the php/ directory. The default is to use 'php/inittags.txt' - if you want to initialise the tags to the contents of 'php/mytags.txt', set tagsfile=mytags (i.e. without the .txt extension)
Update / upgrade / archive account
The updateAccount.php call lets you change user signatures / passwords and also upgrade an account from a 'standard' user to a 'power' user (able to create workspaces). This is a server-wide setting - there is finer grained control over user permissions and roles at a workspace level. Archiving a user account makes it unaccessible (the user can no longer log in) and frees up the user quota. An archived account can be restored at any time.
http://yoursite.com/annotate/php/updateAccount.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user's account
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&action=update
&sig=jill # (optional) The user's signature
&passwd=sesame # (optional) The user's new annotate password
&licensed=1 # (optional) To upgrade to a 'power' user
&firstname=Jill # (optional) To update full name,
&lastname=Jones # (optional) set both these fields
OR
&action=upgrade/downgrade/archive/unarchive
The return value is either "OK" or "ERR {error message}".
Login as and display given Annotate page
The loginAs.php call lets you create a link which logs a user in to their Annotate account and then displays a given page in Annotate, which by default is the user's workspace list. It could also display the list of documents in a workspace or a specific document. Note: The user must have created the workspace or have been added to it in order to have access.
http://yoursite.com/annotate/php/loginAs.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user's account
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&loc=workspaces.php # The page to display after login
&errloc=http://mysite.org/error.php # An error page to display if login fails
&remember=1 # Store login info in browser cookie
&create=1 # (optional) Create user account if not present:
&licensed=1 # (optional) - upgrade new account to 'power' user
&firstname=Jill # (optional) - To set full name and signature for new account
&lastname=Jones # (optional) - set these fields
&sig=joe # (optional)
&add=1 # (optional) Add user to a given workspace if not added
&ws=123456 # (required if add=1) - workspace ID
&role=3 # (required if add=1) - role ID for the user in the workspace
On visiting the link, the user will be logged in and redirected to the loc address. If there is a problem logging in, the link will redirect the user to the errloc url, with the msg parameter set, e.g. error.php?msg=some_error_msg.
The loc parameter determines the page which will be displayed on login. Suitable values are: documents.php?ws=123456 for the list of documents in that workspace, notes.php?ws=123456 for the index of notes, pdfnotate.php?d=2008-01-01&c=abc123 for a particular document.
You may wish to post-date the request if including the loginAs.php link in a web page - simply increase the request time by the desired number of seconds you want the link to be valid for.
If you need to end the user session, you can use the apiLogout call.
Creating new accounts on the fly if needed
If you set the 'create=1' flag, then a new Annotate account will be created for the given annotateuser if they do not already have an account. You can also set the 'licensed=1' flag to enable the new account to create workspaces. This is a shortcut which combines the standard calls to createAccount.php and updateAccount.php. This can be useful for integrations with external web applications - you can add a signed 'loginAs.php' link on your web application which creates an annotate user account and logs the user in. If the user already has an annotate account, then the 'create=1' settings are ignored and it uses their existing account.
Adding a user to a workspace on the fly
If you set the 'add=1' flag and supply a workspace and role ID, then the user will be added to that workspace with that particular role. To find the workspace ID you can use the apiListWorkspaces.php call. For the role ID you can use apiGetWorkspaceDetails.php . This is specially useful if the account has just been created (via 'create=1' flag) and therefore the user does not belong to any workspace yet. If the user has been added already to the workspace, then the 'add=1'setting is ignored. This means you cannot use it to change the user's role within the workspace, for this you need to use the apiUpdateWorkspaceUsers.php call instead.
Logout via API
The apiLogout.php call ends the user's browser session and redirects to the URL in the loc parameter. If you have used the loginAs call to start a user session, you can use the apiLogout call to end it (e.g. by setting the src of an iframe to apiLogout.php). The argument should be URI encoded; you need to set the browser window location (or iframe src) to the apiLogout url to use it.
apiLogout.php?loc=http://example.com/yourpage.html
Set user preferences
The apiSetUserPref.php call sets the user preferences on the account page; noteColor, noteDisplayStyle.
http://yoursite.com/annotate/php/apiSetUserPref.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user to set
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
POST # you only need to set the prefs you want to update.
¬eColor=2 # note background color (an index from 0 - 20)
¬eDisplayStyle=m # {m, b, h, f} for margin, boxes, hide, footnotes
The return value is OK + msg or ERR + msg.
Set email notifications
The apiSetNotifyPref.php call sets the email notification preferences for the user. See the modules installation guide for details of setting up email notifications on your server.
http://yoursite.com/annotate/php/apiSetNotifyPref.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user to set
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
POST # you only need to set the prefs you want to update.
¬ifications=on # {on,off}- whether to send emails at all
&frequency=immediate # {immediate, hourly, daily}
&doneonly=no # {yes,no} - only when someone clicks 'done'
&others=yes # {yes,no} - email if notes on docs of others
The return value is OK + msg or ERR + msg.
Get account details
The apiGetAccountDetails.php call returns the subscription account details for a given user.
http://yoursite.com/annotate/php/apiGetAccountDetails.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user to get
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
The return value is either a json object with fields subtype, credits, subinfo, billing and sig or "ERR {message}".
List user accounts
The listUsers.php call lists the annotate users on the server. To get the users in a given workspace, check the apiGetWorkspaceDetails call.
http://yoursite.com/annotate/php/listUsers.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=joe@example.com # Set this to the api-user
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
The response is "ERR {error message}" or a JSON string with two arrays; "members" lists email addresses of group members, and "annotators" lists email addresses of 'standard' users, e.g.:
{
members : ["joe@example.com","jill@example.com"],
annotators : [ "other@example.com" ]
}
List user's activity log
You can extract the activity log for a given user, which contains the timestamps and IDs of notes they have added. This can be useful to keep track of how much time each user has spent annotating. The admin user can also extract a log of activity by all users in the account.
http://yoursite.com/annotate/php/listActivity.php?
api-user=joe@example.com
&api-requesttime=1234566
&api-annotateuser=jill@example.com
&api-auth=ABC123...
&allusers=0 # set to 1 to return activity for all users in account
The return value will either be "ERR {some error message}" or a JSON encoded array with fields time - the date and time the note was added (GMT); type - usually "note", "reply"; docdate, doccode - the document ids; noteid the ID of the note. If allusers=1 then the user field is also set.
[
{
user: "joe@example.com", // user field only set if allusers=1
time: "2009-02-18 16:27.46",
type: "note",
docdate: "2009-01-01",
doccode: "abc123",
noteid: 29
},
{
// ... more activity log entries
}
]
Delete user account
The apiDeleteAccount.php call removes a user account. It needs to be called by an admin user. The call de-licenses the user before deleting. To downgrade a user to a 'standard' user, you can use the updateAccount api call and set licensed=0.
http://yoursite.com/annotate/php/apiDeleteAccount.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user to delete
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
POST parameter:
delete=1 # To confirm delete
The return value is either "OK" or "ERR {error message}".
