School admins can configure targets to listen for events that happen inside of their school in Schoology. There are three important objects in understanding how to set up a resource to listen for certain events:
- Triggers: are Schoology defined actions that will cause a check for target subscriptions for that action in the school the action took place.
- Targets: are user defined objects specifying where data, called Event Objects, about the action that took place should be sent.
- Subscriptions are the relationships between Schoology triggers and user-defined Targets. Users can subscribe to have multiple targets per trigger, or, alternatively, have one target listen to all Schoology defined triggers.
Targets
Schoology exposes a UI in the admin panel, as well as programmatic endpoints to maintain targets. A user must have access to the Schoology Trigger UI to act on these endpoints. A target object looks like the following:
Field | Name | Description | Type | Required |
---|---|---|---|---|
Id | id | The Schoology Id of the target | integer | |
Target | target | The URL of the target resource. This is where data will be sent when a trigger action occurs. | string | true |
Description | description | Optional description of the target. | string |
Operations - triggers/targets
list
List a schools targets
Path |
|
Return |
A object containing a list of target objects |
create
Create a target
Path |
|
Content |
An object containing target fields |
Return |
An object containing target fields |
Operations - triggers/targets/[target_id]
edit
Modify a target
Path |
|
Content |
An object containing target fields |
Return |
delete
Delete a target
Path |
|
Content | |
Return |
Subscriptions
Once you have your targets made, you then have to define a relationship between targets and triggers. The subscription endpoints will allow you to do this
Field | Name | Description | Type | Required |
---|---|---|---|---|
Target Id | target_id | The Schoology Id of the target you would like to relate to the specified trigger | integer | true |
Trigger Name | trigger | The name of the trigger you are subscribing this target to | string | true |
Subscription Status | subscribed | Whether or not the target is subscribed to this trigger. In the list call this will always be 0, use this flag in the PUT call to subscribe and unsubscribe | {0,1} | true |
API Version | version | What version of the API this subscription should belong to. Right now we only support v1 | string - v1 | |
Include Object | include_object | Whether or not to include the extended data in the return object. If not included, defaults to 0 | {0,1} |
Operations - triggers/subscriptions
list
List all subscriptions for the users school
Path |
|
Content | |
Return |
An object containing an array of subscription objects in the 'subscription' attribute |
subscribe
Create and modify subscription relationships
Path |
|
Content |
An object containing an array of subscription objects in the 'subscription' attributes |
Return |
An object containing an array of statuses and messages about the success of the subscription action |
Example JSON of this call would look like:
{ "subscription" : [ {"target_id" : 373221, "trigger" : "grades", "subscribed" : 1, "include_object": 1}, {"target_id" : 373221, "trigger" : "attendancesdf", "subscribed" : 0, } ] }
Example Return
{ "subscription": [ { "item": { "target_id": 373221, "trigger": "grades", "version": "v1", "subscribed": 1, "target_url": "http:\/\/school.schoology.com\/trigger", "include_object": "1" }, "status": 200 }, { "item": { "target_id": 373221, "target_url": null, "trigger": "attendancesdf", "subscribed": 0, "version": null, "include_object": null }, "message": "The trigger with name attendancesdf does not exist", "status": 400 } ] }