READynamic

API Function Calls: Users and Groups

Create a User Account

You can use a POST request to create a new user account for READynamic. Include in the request the account name, user email address, and initial password:

curl -X POST --header "Content-Type:application/json" -d '{"account_type":"free", "user": {"full_name":"New READynamic User", "preferred_name":"Test", "email":"user@user.com", "password":"1234abcd", "password_confirmation":"1234abcd"}}' http://boxcollege.readynamic.com/users.json

READynamic will create the new user account and provide a JSON response statement, like this:

{
  "id":192,
  "full_name":"New READynamic User",
  "preferred_name":"Test",
  "email":"user@user.com",
  "show_tutorials":true,
  "accepted_eula":false,
  "preferred_locale":"en",
  "confirmed_at":null,
  "role_ids":[3,4],
  "used_space":0,
  "used_space_limit":52428800
}

Note that READynamic assigns an identification number (id) to the new user. In this example the user has identification number 192.

After you place the request to create a new user account, READynamic responds by sending the new user an electronic mail message with a link to confirm his or her access to the product.  By default, the user will not be able to log on to READynamic portal until he or she clicks the this email confirmation link.

Account Types, or Roles

When you create an account in READynamic for a user, part of the process is to grant that user the ability to create eBooks and groups in the system, and define the amount of storage space available to that user for maintaining eBook files.

The account_type parameter defines the level of access permission granted to the user for working with READynamic features. It can also define a customer subscription and payment level, such as free, premium, or unlimited.

Each account type, also known as a “role,” has a pre-defined set of access characteristics. When you apply an account type to a user account, that user account inherits the characteristics assigned to the account type.

In the above example, the command syntax includes this statement:

account_type:"free"

The account was assigned to the “free” account type, meaning the student does not need to pay to access the READynamic portal.

These are the standard account types to select from when creating a new user account:

  • student. Basic access to eBook content within groups that the user is assigned to, or to eBook titles provided to the user directly.
  • teacher. Unlimited storage space, and the ability to create eBooks, restricted eBooks, and groups.
  • instructor. Similar to teacher, in that the instructor can edit eBooks, but may not upload new eBooks or create groups.
  • free. This access to READynamic is provided for free. Limited storage space provided. The user may upgrade to a paid subscription level with more access rights.  A user with this account type may create an eBook and create a group.
  • premium. This is meant to be the next subscription level up from the free account type. The user with this role is provided over 1 GB of storage space, but also may downgrade to a lower subscription level.  The user may create eBooks, restricted eBooks, and groups.

These account types may not all apply to your institution. If you don’t charge for access to the READynamic environment, for example, you likely won’t assign free or premium to a user account. Also, you will find a longer list of user account types in the configuration file roles.yml. Some of these account types are specialized and not commonly used.

The API Reference documentation provides more detail for creating users.

Create a Group

In READynamic, individual users can be added to groups, so that access to eBooks may be shared. A good example of a group would be a college class, or an accounting department in a small technology firm. A set of texts, articles, and recommended reading documents in PDF or ePUB format could be assigned to a group, and every user who is later added to that group would automatically have access to all of the resources owned by that group.

So every Biology student who enrolls in Principles of Ecology 410 or Botany: Marine Ecosystems 425 would be granted access to the textbooks and articles available to that class (group). And every employee in the Technical Support Department could be given access to a set of eBooks that are intended for internal training for the firm’s products and services.

The person who creates a group in READynamic becomes the owner of that group. Only publishers and administrators have the authority to create groups, so to create a group you must provide your Authentication Token, to show that you have the access rights needed to create a group.

To create a group use this command syntax:

curl -d 'group[name]=Botany425' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/current_user/groups

You can also specify a description and access type when creating a group:

curl -d 'group[name]=Botany425&group[description]=Marine Ecosystems&group[access_type]=restricted' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/current_user/groups

READynamic will create the new group account and provide a JSON response statement, like this:

{
  "id":6,
  "owner_id":10,
  "name":"Botany425",
  "description":"Marine Ecosystems",
  "access_type":"restricted",
  "book_category":null,
  "email":"admin@boxcollege.readynamic.com",
  "owner":"administrator",
  "total_contacts":0,
  "is_owner":true,
  "is_member":true,
  "invitation_code":null,
  "pending_request":false
}

In the above example, READynamic assigns the new group its own identification number, 4 (“id”: 4).

The access_type can be public, restricted, or private.

A public book can be downloaded and read by any user. The restricted and private access types are similar, in that they both define a book as having limited access. A private eBook is only available to the single user who owns that book. The owner can read the book but is not permitted to share it with others. A restricted eBook refers to a book that is not available to the public, but the owner of a restricted eBook can grant access to that book to other users or groups, such as by giving or lending the title.

Private and restricted access rights are functionally the same, but you can also set a private eBook to be not available to other users who might search for it. If you want to change the rights to a private title so that other users can find it in the database, you can change a setting so that it will be searchable, but you don’t have to grant access to that eBook to others.  For a public title, or a private title, the Access Control List (ACL) file is disabled.

If you don’t provide an access type for a new group, READynamic will set it to “private” by default.

The API Reference documentation provides more detail for creating groups.

Add a User Contact

Any READynamic user can add another user as a contact. And that user can be added to another user’s account as a contact.

Think of a contact as a friend, and adding a contact as adding a friend to a list of friends or connections. If a READynamic users adds another to his or her contact list, the user can grant that user contact access to one of his or her eBooks, either as a loan or as a gift. So if David Smith adds user Robert Jones to his contact list, Robert Jones will be able to access and read any eBooks that David Smith owns and holds on his bookshelf.

A user contact may be added in READynamic in two ways. One user can add another user to his or her contact list, effectively granting that user access to all of the titles the first user owns.  Or a user can be added as a contact directly to a specific eBook, granting that user access to that title.

Both methods, adding a user contact to another user, and adding a user contact to an eBook, are available in the READynamic Portal user interface. In the Portal, click the People tab to add a user contact to your user account record.

To add a user contact to a specific eBook, click the information icon Information icon for an eBook on your bookshelf, to open the Access Control Panel.

Then, click the arrow next to type and select “New Contact.”

You can also complete either process using READynamic API calls. We describe how to add another user as a contact to a user record in this section. To add a user contact record directly to a specific eBook, see Grant a User Contact Direct Access to an eBook.

To add a user as a contact, the user must be registered in READynamic. Also, a user can only be added as a contact once.  If David Smith adds Robert Jones to his contact list and then forgets and tries to add him again, the second request will fail.

The Authentication Token is required for the user adding the new contact.

Here is a sample command syntax:

curl -X POST -b 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' --header "Content-Type:application/json" -d '{"email":"RJones@boxcollege.readynamic.com","name":"R Jones"}' http://boxcollege.readynamic.com/portal/api/current_user/contacts'

In the command example, the user being added as a contact is identified by entering that user’s email address.

READynamic responds with this JSON content:

{
  "id": 83,
  "owner_id": 1,
  "user_id": 195,
  "name": "R Jones",
  "groups": [],
  "email": "RJones@boxcollege.readynamic.com"
}

The API Reference documentation provides more detail for user contacts.

Grant a Contact Access to a Group

After you create a group you need to add members to that group. The group members share access to the resources owned by that group. For example, after setting up a group for a Botany class, Marine Ecosystems 425, you would want to add the 15 students for the class, and you would do this by adding user contacts to the group. So each member of the group would need to be made a contact first (see Add a User Contact).

To add the contact to the group using the READynamic User Portal, click the People tab and then click the icon for the group, Botany: Marine Ecosystems 425. Select “Contacts” under Type and choose the contact you want to add to the group in the Contacts drop down list. Click Grant Access.

You can also complete the process using a READynamic API call. We describe this below.

The Authentication Token is required for the user contact record.

Use this command syntax:

curl -X POST --header "Content-Type:application/json" -b 'auth_token=SL1Gz0rCuL4_Ms0dUY-kCg' -d '{"email":"RJones@boxcollege.readynamic.com","group_id":"91"}' http:/boxcollege.readynamic.com/portal/api/current_user/groups/:id/add_contact

In the command example, the contact being added is identified by entering that user’s email address, and the group to receive the new contact is group number 91.

READynamic responds with this JSON content:

{
  "id": 1799,
  "owner_id": 1,
  "user_id": 5441,
  "name": "R Jones",
  "groups": [{"id":91}],
  "email": "RJones@boxcollege.readynamic.com"
}

The API Reference documentation provides more detail for adding a contact to a group.

Note that you can combine steps too, and create a command syntax that can both add a contact and assign that new contact to a group at the same time.

Most of the time when you assign a contact to a group the contact will already exist in READynamic, but not always. Suppose you had a group of new students that have just enrolled in your institution, and they all want to register for the same class. So you could use this command syntax to add that new contact and assign the new contact to group (class) number 91:

curl -X POST -b 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' --header "Content-Type:application/json" -d '{"email":"RJones@boxcollege.readynamic.com","group_id":"91"}' http://boxcollege.readynamic.com/portal/api/current_user/user_signup_invitations

Remove a Contact from a Group

Sometimes you will want to remove a member from a group, as when a student drops a class.

To remove a contact from a group using the READynamic User Portal, click the People tab and then click the icon for the group. Note the list of contacts related to this group.  Check the box next to the contact you want to delete and then click the red X that appears above the list.

You can also complete the process using a READynamic API call. We describe this below.

The Authentication Token is required for the user contact record.

Use this command syntax:

curl -X DELETE --header "Content-Type:application/json" -b 'auth_token=SL1Gz0rCuL4_Ms0dUY-kCg' -d '{"email":"RJones@boxcollege.readynamic.com","group_id":"91"}' http:/boxcollege.readynamic.com/portal/api/current_user/groups/:id/remove_contact

In the command example, the contact being removed is identified by entering that user’s email address, and the group to receive the new contact is group number 91.

READynamic responds with this JSON content:

{
  "id": 1799,
  "owner_id": 1,
  "user_id": 5441,
  "name": "R Jones",
  "groups": [],
  "email": "RJones@boxcollege.readynamic.com"
}

The API Reference documentation provides more detail for removing a contact from a group.

Invite a User to READynamic

You can also send a message to a friend to invite that person to sign up as a READynamic user. To invite a prospect to sign up for READynamic, enter this command:

curl -d 'email=newuser@web.com' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/current_user/user_signup_invitations

The request fails if someone has already sent an invitation to this user. READynamic responds with an error message.

Granting Access to a Restricted eBook

A public eBook can be downloaded and read by any user, while a restricted title has limited access.  A restricted eBook is only available to a user who has purchased it, though the owner may be able to lend the title or give it to other users, or to a group or groups.

A private eBook is similar to a restricted title, in that it must be purchased for access, but it is only available to the person who owns it.  The owner of a private eBook may not share it with others, and a private eBook also may not appear as a result when other users search for available titles in the database.

To share a restricted eBook with another user, that user must be added to the contact list of the book owner, and then that contact must be added to the eBook Access Control List.

Grant a User Contact Direct Access to an eBook

This API call serves to add a user contact record directly to the Access Control List (ACL) file for a specific eBook, granting that user access rights to the eBook.

The command statement must include the book ID to identify the book involved, and generally the command should also include the annotation set ID code (annotation_sets/94) as well.

http://boxcollege.readynamic.com/portal/api/books/book_id/annotation_sets/annotation_set_id/acl_entries/contacts

In this sample command statement, the book ID code is 97 and the annotation set number is 94:

curl -X POST -b 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' --header "Content-Type:application/json" -d '{"contact_id":83}' http://boxcollege.readynamic.com/portal/api/books/97/annotation_sets/94/acl_entries/contacts

If you don’t know the annotation set ID, you can use a GET statement to query the book record in the READynamic database, searching on the book ID code (/portal/api/books/book_id).

You need to identify the user account to be added to the eBook Access Control List. The best way to do that would be to add the user ID for that user to the command statement:

curl -X POST -b 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' --header "Content-Type:application/json" -d '{"user_id":195}' http://boxcollege.readynamic.com/portal/api/books/97/annotation_sets/94/acl_entries/contacts

You can also add a user to the book ACL using that user’s contact ID code:

curl -X POST -b 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' --header "Content-Type:application/json" -d '{"contact_id":83}' http://boxcollege.readynamic.com/portal/api/books/97/annotation_sets/94/acl_entries/contacts

Or you can identify the user with that user’s email address:

curl -X POST -b 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' --header "Content-Type:application/json" -d '{"email":"MSmith@boxcollege.readynamic.com"}' http://boxcollege.readynamic.com/portal/api/books/97/annotation_sets/94/acl_entries/contacts

One of these three values is required, but only one.  The user ID code would take precedence over the email address or contact ID number.

You can also add an optional parameter to define the type of ACL entry, readonly or createas. By default the user (contact) can add changes to the eBook title.  A user with read only access to an eBook can only look at and read the content. A user with create as access rights can make edits to the eBook, but can only grant another user access to these additions to the eBook content if that other user already has access rights to that book.

curl -X POST -b 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' --header "Content-Type:application/json" -d '{"contact_id":83}' '{"type": readonly}'
http://boxcollege.readynamic.com/portal/api/books/97/annotation_sets/94/acl_entries/contacts

READynamic responds with this JSON content:

{
  "id": 53,
  "contact": {
    "id": 83,
    "owner_id": 1,
    "user_id": 195,
    "name": "M Smith",
    "groups": [],
    "email": "MSmith@boxcollege.readynamic.com"
  },
  "annotation_set": {
    "id": 94,
    "name": "No Additions"
  }
}

Grant a Group Access to an eBook

After a group is in place, such as for a botany class or for a tech support department, the owner of that group (the person who created it) can grant that READynamic group access to eBooks. These files will be shared with every user who is a member of that group.

The command statement must include the book ID and the annotation set ID to identify the eBook title.

http://boxcollege.readynamic.com/portal/api/books/book_id/annotation_sets/annotation_set_id/acl_entries/groups

The owner of the group must also provide his or her Authentication Token to confirm for READynamic that this person is in fact the owner of the group, and an owner of the eBook as well. The group ID number is also required to identify the group.

The command might look like this:

curl -X POST -b 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' --header "Content-Type:application/json" -d '{"group_id":91}'
http://boxcollege.readynamic.com/portal/api/books/15/annotation_sets/2/acl_entries/groups

In this case the command will grant group #91 access to eBook #15 and access to annotation set (version) #2.

READynamic responds with this JSON code:

{
 "id":91,
 "expiration":null,
 "group":
  {
    "id":15,
    "owner_id":1,
    "name":"Botany425",
    "description":"Marine Ecosystems",
    "access_type":"restricted",
    "book_category":null,
    "email":"admin@boxcollege.readynamic.com",
    "owner":"administrator",
    "total_contacts":0,
    "is_owner":true,
    "is_member":true,
    "invitation_code":null,
    "pending_request":false 
  },
    "annotation_set":
    {
    "id":2,
    "name":"Revision 2"
    }
}