Gem Version Build Status Coverage Status

Agilix Buzz

Fully Implements the Agilix Buzz API in Ruby

Installation

Add this line to your application's Gemfile:

gem 'agilix'

And then execute:

$ bundle

Or install it yourself as:

$ gem install agilix

Be sure to define your Agilix Buzz credentials by setting up environment variables in your application appropriately. Refer to the .env.sample file for details.

AGILIX_BUZZ_USERNAME = 'my-username'
AGILIX_BUZZ_PASSWORD = 'my-password'

Optionally, if your Buzz instance runs on your own url, you can define it as well:

AGILIX_BUZZ_URL = 'https://api.mycustomdomain.com'

Usage

There are many primary APIs that are wrapped. Below you will see basic examples of how to use them. For more information about what optional query parameters are available, please consult the Agilix Buzz API Docs

Auth

You need to authenticate to use the api. Set the credentials in Environment variables as seen above. If you've done that, you can set and refernce the api object by:

api = Agilix::Buzz::Api.new

Otherwise, you can pass :username, :password, and :domain into the initializer

api = Agilix::Buzz::Api.new username: 'my-username', password: 'my-password', domain: 'my-domain'

The authentication API gives you back a token that can be used within a 15 minute window. This library will manage the need to fetch a new token or extend_session by setting the token & token expiration in the initialized api object.

Passing arguments

All APIs have defined required arguments and optional arguments, and an argument cleaner will prevent the calls from being made if conditions are not met. Additionally it will strip out any unsupported api params that are not defined in the required or optional fields.

Below are instructions for basic invocation of the api methods. For additional information about each API method, please consult the Agilix documentation, linked in each method's name.

Domains

CreateDomains

api.create_domains [{name: "BuzzTest1", userspace: 'buzz-test-fc-1', parentid: '57025'}]

DeleteDomain

api.delete_domain domainid: '57027'

GetDomain2

This is aliased to get_domain

api.get_domain domainid: '57025'

GetDomainContent

api.get_domain_content domainid: '57025'

GetDomainEnrollmentMetrics

api.get_domain_enrollment_metrics domainid: '57025'

GetDomainParentList

api.get_domain_parent_list domainid: '57025'

GetDomainSettings

api.get_domain_settings domainid: '57025', path: "AgilixBuzzSettings.xml"

GetDomainStats

api.get_domain_stats domainid: '57025', options: "users|courses"

ListDomains

api.list_domains domainid: '57025'

RestoreDomain

api.restore_domain domainid: '57027'

UpdateDomains

api.update_domains [{ domainid: "57027", name: "BuzzTestUpdated1", userspace: 'buzz-test-fc-1', parentid: '57025'}]

Reports

get_runnable_report_list and run_report are probably the only ones you would use.

GetReportInfo

api.get_report_info reportid: 127

GetReportList

api.get_report_list domainid: 1

GetRunnableReportList

api.get_runnable_report_list domainid: 57025

RunReport

api.run_report reportid: 127, entityid: 57025, format: 'json'

Users

CreateUsers2

This is aliased to create_users

api.create_users( [{
  domainid: '57025',
  username: "BuzzUserTest1",
  email: '[email protected]',
  password: 'testpassword1234',
  firstname: 'Buzz',
  lastname: "Man",
  passwordquestion: "Who's your best friend?",
  passwordanswer: "Me"
  }] )

DeleteUsers

api.delete_users [userid: '57181']

GetActiveUserCount

api.get_active_user_count domainid: '57025'
api.get_active_user_count domainid: '5', includedescendantdomains: true, bymonth:true, startdate: '2018-01-01', enddate: '2019-03-01'

GetDomainActivity

api.get_domain_activity domainid: '57025'

GetProfilePicture

Returns base 64 encoded picture

api.get_profile_picture entityid: 57026

The api will return 404 not found if they don't have one, unless you supply it with a default profile pic, then it will return that

api.get_profile_picture entityid: 57025, default: "https://www.gravatar.com/avatar/00000000000000000000000000000000?d=mm"

GetUser2

This is aliased to get_user

api.get_user userid: 57026

GetUserActivity

api.get_user_activity userid: 57026

GetUserActivityStream

api.get_user_activity_stream userid: 57026

ListUsers

api.list_users domainid: 57025

RestoreUser

api.restore_user userid: 57026

UpdateUsers

api.update_users  [{ userid: '57026', username: "BuzzUserTestUpdated1", email: '[email protected]',firstname: 'Buzz', lastname: "ManUpdated"}]

Second Priority

Authentication

Login2

This is handled automatically by instantiation of a base Agilix::Buzz::Api instance. It wouldn't need to be called manually unless using for other users or making calls on their behalf

api. username: 'my-username', password: 'my-password', domain: 'my-domain'

Logout

Clears your login session

api.logout

ExtendSession

This is handled automatically by instantiation of a base Agilix::Buzz::Api instance and on subsequent calls to the api through the check_authentication method

api.extend_session

ForcePasswordChange

api.force_password_change userid: 57181

GetPasswordLoginAttemptHistory

api. userid: 57181
api. userid: 57181, earliestrecordtoreturn: '2018-01-01'

GetPasswordPolicy

For current domain

api.get_password_policy

for a specific domain

api.get_password_policy domainid: 57031

GetPasswordQuestion

api.get_password_question username: "auto-tests/BuzzUserUp1"

UpdatePasswordQuestionAnswer

ISSUE: This works with a GET call

api.update_password_question_answer userid: 57181, passwordquestion: "Where is your favorite vacation place?", passwordanswer: "Hawaii"

Proxy

  api.proxy userid: 57181

In addition to these, we've created a proxy api method that will setup an api client for the proxied connection:

Proxy Api

proxy_api = api.proxy_api userid: 57181

This will allow you to make requests as the proxied user, like you would the main api user. It's required to demonstrate how unproxy works below

Unproxy

First setup a proxy_api

proxy_api = api.proxy_api userid: 57181

Then you can unproxy out of it to logout as the proxied user

proxy_api.unproxy userid: 57181

ResetLockout

api.reset_lockout userid: 57181

ResetPassword

api.reset_password username:'auto-tests/BuzzUserUp1'

UpdatePassword

api.update_password userid: 57181, password: "IChanged123"

PutKey

ISSUE: This should be a POST method as it's storing data

api.put_key entityid: 57031, name: 'secret_key_1', value: "Super Secret"

GetKey

api.get_key entityid: 57031, name: 'secret_key_1'

ComputeHMAC

This requires a key to exist with the given keyname, see put_key. not sure what its used for yet

api.compute_hmac domainid: 57025, keyname: "secret_key_1", message:"my-secret-1"

Courses

CopyCourses

api.copy_courses [{courseid: 60982, domainid: 57025}]

CreateCourses

api.create_courses title: "Starter Course", domainid: 57025

CreateDemoCourse

ISSUE: documentation on request format is inconsistent, not sure if it is bulk

api.create_demo_course courseid: 60982, domainid: 57025, title: "Demo Course",

DeactivateCourse

ISSUE: get request should be delete, put, patch

api.deactivate_course

DeleteCourses

ISSUE: Why so different than deactivate course

api.delete_courses [{courseid: 60994}]

GetCourse2

api.get_course2 courseid: 60994

GetCourseHistory

api.get_course_history courseid: 60994

ListCourses

api.list_courses domainid: 5

MergeCourses

api.merge_courses courseid: 60994

RestoreCourse

api.restore_course courseid: 60994

UpdateCourses

api.update_courses [{courseid: 60994, title: "Updated Course"}]

Enrollments

CreateEnrollments

ISSUE: API format is very inconsistent on this one, requires both query string modification & body modification

api.create_enrollments [{userid: 57026, entityid: 57025}]

DeleteEnrollments

ISSUE: Inconsistent from other delete apis. many are singular, not plural

api.delete_enrollments [ { enrollmentid: 60997 }]

GetEnrollment3

This is aliased to get_enrollment

api.get_enrollment enrollmentid: 60997

GetEnrollmentActivity

api.get_enrollment_activity enrollmentid: 60997

GetEnrollmentGradebook2

api.get_enrollment_gradebook enrollmentid: 60997

GetEnrollmentGroupList

api.get_enrollment_group_list enrollmentid: 60997

GetEnrollmentMetricsReport

This is available in two types: Student Report

api.get_enrollment_metrics_report entityid: 50725, report: "Student"

Enrollment Report

api.get_enrollment_metrics_report entityid: 50725, report: "Enrollment"

ListEnrollments

api.list_enrollments domainid: 50725

ListEnrollmentsByTeacher

api.list_enrollments_by_teacher teacheruserid: 50726

# If you don't pass in a teacher user id, it will default to the logged in API user

api.list_enrollments_by_teacher

ListEntityEnrollments

api.list_entity_enrollments entityid: 60982

ListUserEnrollments

api.list_user_enrollments userid: 57181

PutSelfAssessment

ISSUE: this should be a post, not a get

api.put_self_assessment enrollmentid: 60997, understanding: 200, effort: 220, interest: 100

RestoreEnrollment

api.restore_enrollment enrollmentid: 60997

UpdateEnrollments

api.update_enrollments [{enrollmentid: 60997, status: 7}]

General

Echo

api.echo test: 'param'

GetCommandList

api.get_command_list

GetEntityType

ISSUE: nothing saying this is an authenticated call, when others are non-authenticated

api.get_entity_type entityid: 57025

GetStatus

ISSUE: docs in getting started reference a level param, actual docs suggest using rating

api.get_status rating: 4, html: true, sms: true

# you can also call this one non-authenticated
api.get_basic_status

GetUploadLimits

ISSUE: Docs have cmd spelled wrong, this API doesn't seem to work at all AccessDenied. It did say experimental

api.get_upload_limits
api.get_upload_limits domainid: 57025

SendMail

This is one of the more confusing APIs, it allows you to send emails to people in the same enrollment grouping as the person wanting to send the email (enrollmentid).

api.send_mail subject: "Test email", body: "Did you get this?", enrollmentid: 60997, enrollment_ids: ["all"]

Resources

CopyResources

api.copy_resources [ {sourceentityid: 57025, destinationentityid: 57031, sourcepath: "banner.css" }]

DeleteResources

api.delete_resources [{entityid: 57031, path: 'banner.css'}]

GetEntityResourceId

api.get_entity_resource_id entityid: 57025

GetResource

api.get_resource entityid: 57031, path: "banner.css"

GetResourceInfo2

ISSUE: This is a get request with a POST verb. The documentation only suggests getting a single resoure, so I'm not sure why it would be a bulk post syntax. it does seem to respond to multiple resources though,so we'll adapt

api.get_resource_info  [{entityid: 57031, path: "banner.css"}]

GetResourceList2

api.get_resource_list entityid: 57025

ListRestorableResources

api.list_restorable_resources entityid: 57025

PutResource

file_name = "my-file.pdf"
file = File.open file_name
api.put_resource file, {entityid: 57025, path: file_name}

PutResourceFolders

api.put_resource_folders [{entityid: 57031, path: 'test/folder-1'}]

RestoreResources

api.restore_resources [{entityid: 57031, path: 'banner.css'}]

Rights

CreateRole

ISSUE: Why is this create singular, not multiple?

api.create_role domainid: 57025, name: "Test Role", privileges: api.right_flags[:create_domain]

DeleteRole

api.delete_role roleid: 61316

DeleteSubscriptions

ISSUE: Why is this create singular, not multiple?

api.delete_subscriptions subscriberid: 57181, entityid: 57025

GetActorRights

ISSUE: Why is this create singular, not multiple?

api.create_role domainid: 57025, name: "Test Role", privileges: api.right_flags[:create_domain]

GetEffectiveRights

api.get_effective_rights entityid: 57025

GetEffectiveSubscriptionList

api.get_effective_subscription_list

GetEntityRights

api.get_entity_rights entityid: 57025

GetEntitySubscriptionList

api.get_entity_subscription_list entityid: 57025

GetPersonas

api.get_personas userid: 57026

GetRights

api.get_rights actorid: 57026, entityid: 57025

GetRightsList

api.get_rights_list domainid: 57025

GetRole

api.get_role roleid: 61316

GetSubscriptionList

# Get for a domain
api.get_subscription_list subscriberid: 57025
# Get for a user
api.get_subscription_list subscriberid: 57026

ListRoles

api.list_roles domainid: 57025

RestoreRole

api.restore_role roleid: 61316

UpdateRights

api.update_rights [ {actorid: 57026, entityid: 57025, roleid: 61316}]

UpdateRole

api.update_role roleid: 61316, name: "Test Role Updates", privileges: api.right_flags[:update_domain]

UpdateSubscriptions

ISSUE: Why is this root node singular?

api.update_subscriptions subscriberid: 57181, entityid: 60982, startdate: "2019-03-15", enddate: "2019-03-15"

Third Priority

Assessments

Manifests and Items

Ratings

Resources

- [ ] RestoreDocuments

Not Prioritized

Announcements

Badges

Blogs

Command Tokens

Conversion

Discussion Boards

Groups

Gradebook

Objectives

Peer Grading

Signals

Submissions

Wikis

Features

Implemented APIs from Agilix Buzz API Docs

(Last updated on March 7, 2019)

API Methods & Docs Implemented? Priority
Announcements DeleteAnnouncements, GetAnnouncement, GetAnnouncementInfo, GetAnnouncementList, GetUserAnnouncementList, ListRestorableAnnouncements, PutAnnouncement, RestoreAnnouncements, UpdateAnnouncementViewed ❌ 🔼
Assessments DeleteQuestions, GetAttempt, GetAttemptReview, GetExam, GetNextQuestion, GetQuestion, GetQuestionScores, GetQuestionStats, GetSubmissionState, ListQuestions, ListRestorableQuestions, PrepareOfflineAttempt, PutQuestions, RestoreQuestions, SaveAttemptAnswers, SubmitAttemptAnswers, SubmitOfflineAttempt ❌ ⏺
Authentication ExtendSession, GetKey, ForcePasswordChange, GetPasswordLoginAttemptHistory, GetPasswordPolicy, GetPasswordQuestion, Login2, Logout, Proxy, PutKey, ResetLockout, ResetPassword, Unproxy, UpdatePassword, UpdatePasswordQuestionAnswer ❌ 🔼
Badges CreateBadge, DeleteBadge, GetBadge, GetBadgeAssertion, GetBadgeList ❌ 🔽
Blogs DeleteBlogs, GetBlog, GetBlogList, GetBlogSummary, GetRecentPosts, PutBlog, UpdateBlogViewed ❌ ⏬
Command Tokens CreateCommandTokens, GetCommandToken, GetCommandTokenInfo, DeleteCommandTokens, UpdateCommandTokens, ListCommandTokens, RedeemCommandToken ❌ ⏬
Conversion ExportData, GetConvertedData, ImportData ❌ ⏬
Courses CopyCourses, CreateCourses, CreateDemoCourse, DeactivateCourse, DeleteCourses, GetCourse2, GetCourseHistory, ListCourses, MergeCourses, RestoreCourse, UpdateCourses ❌ 🔼
Discussion Boards DeleteMessage, DeleteMessagePart, GetMessage, GetMessageList, ListRestorableMessages, PutMessage, PutMessagePart, RestoreMessages, SubmitMessage, UpdateMessageViewed ❌ 🔽
Domains CreateDomains, DeleteDomain, GetDomain2, GetDomainContent, GetDomainEnrollmentMetrics, GetDomainParentList, GetDomainSettings, GetDomainStats, ListDomains, RestoreDomain, UpdateDomains ✅ ⏫
Enrollments CreateEnrollments, DeleteEnrollments, GetEnrollment3, GetEnrollmentActivity, GetEnrollmentGradebook2, GetEnrollmentGroupList, GetEnrollmentMetricsReport, ListEnrollments, ListEnrollmentsByTeacher, ListEntityEnrollments, ListUserEnrollments, PutSelfAssessment, RestoreEnrollment, UpdateEnrollments ❌ 🔼
General Echo, GetCommandList, GetEntityType, GetStatus, GetUploadLimits, SendMail ❌ ⏺
Groups AddGroupMembers, CreateGroups, DeleteGroups, GetGroup, GetGroupEnrollmentList, GetGroupList, RemoveGroupMembers, UpdateGroups ❌ ⏬
Gradebook CalculateEnrollmentScenario, GetCalendar, GetCalendarItems, GetCalendarToken, GetCertificates, GetDueSoonList, GetEntityGradebook2, GetEntityGradebook3, GetEntityGradebookSummary, GetEntityWork2, GetGrade, GetGradebookList, GetGradebookSummary, GetGradebookWeights, GetGradeHistory, GetItemAnalysis2, GetItemReport, GetRubricMastery, GetRubricStats, GetUserGradebook2 ❌ 🔽
Manifests and Items AssignItem, CopyItems, DeleteItems, FindPersonalizedEntities, GetCourseContent, GetItem, GetItemInfo, GetItemLinks, GetItemList, GetManifest, GetManifestData, GetManifestInfo, GetManifestItem, ListAssignableItems, ListRestorableItems, NavigateItem, PutItems, RestoreItems, Search2, UnassignItem, UpdateManifestData ❌ ⏺
Objectives CreateObjectiveSets, DeleteObjectiveMaps, DeleteObjectives, DeleteObjectiveSets, GetMasteryDetail, GetMasterySummary, GetObjectiveList, GetObjectiveMapList, GetObjectiveMastery, GetObjectiveSet2, GetObjectiveSubjectList, ListObjectiveSets, PutObjectiveMaps, PutObjectives, RestoreObjectiveSet, UpdateObjectiveSets ❌ ⏬
Peer Grading GetPeerResponse, GetPeerResponseInfo, GetPeerResponseList, GetPeerReviewList, PutPeerResponse ❌ ⏬
Ratings GetItemRating, GetItemRatingSummary, PutItemRating ❌ ⏺
Reports GetReportInfo, GetReportList, GetRunnableReportList, RunReport ❌ ⏫
Resources CopyResources, DeleteDocuments, DeleteResources, GetDocument, GetDocumentInfo, GetEntityResourceId, GetResource, GetResourceInfo2, GetResourceList2, ListRestorableDocuments, ListRestorableResources, PutResource, PutResourceFolders, RestoreDocuments, RestoreResources ❌ ⏺
Rights CreateRole, DeleteRole, DeleteSubscriptions, GetActorRights, GetEffectiveRights, GetEffectiveSubscriptionList, GetEntityRights, GetEntitySubscriptionList, GetPersonas, GetRights, GetRightsList, GetRole, GetSubscriptionList, ListRoles, RestoreRole, UpdateRights, UpdateRole, UpdateSubscriptions ❌ 🔼
Signals CreateSignal, GetLastSignalId, GetSignalList2 ❌ 🔽
Submissions DeleteWorkInProgress, GenerateSubmission, GetScoData, GetStudentSubmission, GetStudentSubmissionHistory, GetStudentSubmissionInfo, GetTeacherResponse, GetTeacherResponseInfo, GetWorkInProgress2, PutItemActivity, PutScoData, PutStudentSubmission, PutTeacherResponse, PutTeacherResponses, PutWorkInProgress, SubmitWorkInProgress ❌ 🔽
Users CreateUsers2, DeleteUsers, GetActiveUserCount, GetDomainActivity, GetProfilePicture, GetUser2, GetUserActivity, GetUserActivityStream, ListUsers, RestoreUser, UpdateUsers ❌ ⏫
Wikis CopyWikiPages, DeleteWikiPages, GetWikiPage, GetWikiPageList, ListRestorableWikiPages, PutWikiPage, RestoreWikiPages, UpdateWikiPageViewed ❌ ⏬
Example Name Example Description ✅ or ❌ ⏫🔼⏺🔽⏬

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/beneggett/agilix. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Agilix::Buzz project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.