I'm a bit confused on how we are supposed to update a group using the Valence API.
According to documentation, "Name,Code & Description" are required for updating, but the FETCH group block only returns "GroupID,Name, Description and Enrollments". If Group Code is not returned in the fetch, what value are we supposed to use in the update block if we only want to update the name? Since description is provided I can just feed that back, but what am I supposed to do about code ... just lose that data?
Perhaps there a way to send an update that will update only specific fields in the update block? When I omit fields from the update block I currently receive an error (ie in the case I only want to update the name).
The Code property for Groups is intended to be the "org-defined code" for the group (for a course offering, this is often called the "course code"), the one that might appear in the organization's SIS system, for example.
Because groups in Desire2Learn's Learning Suite are considered "org units", when you create one, you need to provide it with an appropriate org-defined code (Code) -- if your organization doesn't use org-defined codes for groups, then you can decide to systematically use some other kind of data by convention (a name, a descriptive string, and so on). You are correct that's inconvenient for the Fetch form of the GroupData structure not to provide this value for you, but the value will be accessible to callers through the organization structure routes (because the newly created group is just an special kind of org unit).
In Learning Suite v10.2 (LP API v1.3+) and later, you can use a single GET call to fetch back the properties for an org unit. In versions prior to v10.2, you will need to fetch the list of parents for the group to get a parent org unit ID, or if you already know the org unit ID for the course offering that owns the group you can use that; then you use that org unit ID to fetch its list of children: your group will be in that list. The OrgUnit and OrgUnitProperties structures both contain the Code property that you need here.
Related
Would someone be able to direct me to the correct API that I could use to mark a Student Subject and Course to ‘Complete’?
I found out ‘Grade.CourseCompletion’ API could serve the purpose, but not sure if that's correct understanding.
Also, where could I find below highlighted fields and how I can change their value?
"OrgUnitId": <number:D2LID>,
**"CompletionId": <number:D2LID>,**
"UserId": <number:D2LID>,
**"CompletedDate": <string:UTCDateTime>,**
"ExpiryDate": <string:UTCDateTime>|null
Thanks
Vivek
You cannot change a CompletionId; it's an entity identifier for the completion record that gets created by Brightspace when the completion record gets created. (I believe you could, however, delete a completion record and create a new one.)
You use the POST and PUT routes for course completion to create new (or update existing) course completion records. The JSON structure you provide when you do a create or update operation allows you to specify a CompletedDate.
I would also point out that D2L has a developer-specific community to support clients and partners and you may find that answers to your questions are more timely there.
I'm attempting to get all OrgUnits using Valence that are the "Department" type. When I do the call to /d2l/api/lp/1.4/orgstructure/?orgunittype=Department, I get a paged result set containing all the OrgUnits
The docs are a little unclear. They specify that
You can use the orgUnitType, orgUnitCode, and orgUnitName query parameters as filters to further narrow the list of org units this action retrieves.
and also
orgUnitType (string) – Optional. Filter to org units of this type.
However, "string" is a bit ambiguous considering OrgUnitType is a composite type with both a code and a name as a string. Both my Code and my Name for this type is "Department yet it still gives me everything.
You should provide an org unit type identified by a valid orgUnitTypeId (for course offerings, this will be 3.
For custom org unit types, like "Department", the value will most likely vary LMS to LMS:
You can use the call to retrieve the list of all known org unit types to determine the type corresponding to "Department" for your LMS.
Or, because "Department" is one of the very common custom org unity types, you can use the specific get department-org-unit-type call to find out what the ID is for that type on your LMS (there's also a specific call like this to get the type ID for "semester" org units).
We decided to have some User Groups completely under programmatic control.
Which parameters to use when creating a Group Category, so that:
neither number of groups nor number of students is known in advance
no automatic group creation
auto enrollment not allowed
self enrollment not allowed
?
You should be able to accomplish this with these steps (I am assuming your back-end service supports the LP API contracts of at least version 1.3 and forward):
Create a group category for the groups you want to build in the future like this. In the GroupCategoryData structure you provide to this call, you can use these property settings:
Set EnrollmentStyle to 0 or NumerOfGroupsNoEnrollment (sic: note the mis-spelling).
Set EnrollmentQuantity to null
Set AutoEnroll and RandomizeEnrollments to false
Set MaxUsersPerGroup to null
Set NumberOfGroups to the number of groups you want to create off the start within this group category: you can create 1 and then delete it after the group category creation.
You should get back a GroupCategoryData fetch-form structure that contains an array of any initial Group org unit IDs created within this group category, and containing the GroupCategoryId for this new category.
When you want to create a group for the category, provide the group category ID from the previous step in the POST route to create the group.
To enroll users into these groups, you can use the standard create-enrollment call and provide the standard EnrollmentData structure. You'll need to provide the org unit ID for the group, the user ID for the user to enroll, and the role ID for the role you want the user to have in the group. You should also set IsCascading to false here.
Note that, if your back-end service only has v1.2 of the LP API or older, then these instructions will vary slightly (read the enrollment topic in the API reference carefully).
I understand that in MVC pattern and in REST services it is common to use URIs like /items/{id} but what is bad thing about using query parameters in the URI?
GET /items/{id} vs GET /items?id={id}
Further, lets say an entity has 'referenceId' field that points to some related (say parent) entity, and I need to create REST service to get all items for parent entity, which way is better:
GET(POST) /items/parent/{parentId}
or
GET(POST) /items?parent={parentId}
Will be grateful for insights that would help to resolve my subjective issues on constructing URLs for REST services.
I would use the following schemes.
/items/id
This uniquely addresses a resource of items with id id. We are not using parameters as a parameter to uniquely address this resource (as is the case with the other option). Just as
miguelcobain suggests.
/parent/id/items
Here id is an id to uniquely address a resource of parent and from those we collect/retrieve the items it references. From what you have said in the question it seems that parent references multiple items, like a container or collection.
The convention I use for this is to narrow down the scope going from left to right. Therefore in case items could be active or inactive. Thusly items have a property or attribute to be active or inactive. Narrowing down on this I get the following scheme:
/items/active
/parent/id/active
For your first question:
/items/{id} should retrieve a single resource with the specified id or 404 if it doesn't exist.
/items/?id={id} should retrieve an array (even if only one in the array) because you are querying the collection.
For your second question:
I agree with #miguelcobain's assessment - if the item is a specific resource/entity, just use the proper resource path to retrieve it.
To make this easier on the consumer, create a link header with rel="parent" and/or include the uri in the child resource. For an example of link headers, see GitHub's pagination api.
Of course, REST principles don't care about aesthetic details on URLs. It just imposes that every resource should be uniquely addressable.
Furthermore, using the query parameters to uniquely address something "kind of" violates the semantics of a "parameter", doesn't it? A parameter should be something optional, something additional and parameterized. Something like a detailed search on a collection of items, for example.
What you wrote may make sense in some cases. It depends.
In your example, is the item really a resource? If not, you could just do GET(POST) /parents/{parentId}.
If parent is, say, a boolean, and you want to search the items that have parent equals to true, then using the parameters makes sense. But since you're explicitly saying that you want a parent with a specific id, I assume that parent is a resource itself and I would uniquely address that resource using your option 1.
I hope I made myself clear.
It seems to me there are no rules to follow.
items/{id} - this convention is suitable for GET item by given id. If user doesn't provide id then it returns 404 status code.
items/id={id}&name={name} - this type of convention is suitable for search multiple items by given criteria. If no items are found, it is not a 404 situation, you simply say "I successfully found nothing matching your search criteria"
I have a customer requirement to export the checks written in QuickBooks into a specific format because their bank allows fraud prevention by uploading a file and they verify the name on the check against what you give them before clearing it.
I looked at the QuickBooks SDK (we use the XML to communicate in general) and It references a field on the check called PayeeEntityRef with a FullName property, but typically in QuickBooks that data structure would indicate what the entity is called, not what appears on the check (Vendors have a NameOnCheck property, for example, which can be something other than their name).
Without coding up multiple test cases to demonstrate QuickBooks behavior here, does anyone have experience with getting the name as it was printed on the check? What is the best way to do it?
It's somewhat possible to get what you are wanting, but there are going to be some hiccups that you'll need to let you client know about. The main problem being that there's no way to retrieve the actual name printed on the check.
You would first need to query for the Checks/Bill Payment - Checks for the bank account. Then, using the PayeeEntityRef (I would use the ListID component) figure out which "List" the entity is on; Customer, Vendor, Employee, or Other. I don't know of any way to tell which list the PayeeEntityRef is from other than doing a query for each of the lists.
If the PayeeEntityRef is a Vendor or Employee, then you can retrieve the NameOnCheck value. The only thing you would need to keep in mind is that if the NameOnCheck has been modified AFTER the check was printed, the names will not match.
If the PayeeEntityRef is a Customer or Other name, then you have to do a little bit more. The value that QuickBooks uses for the printed name is based on what fields are filled out for the customer record. It first will use the CompanyName field if it is not null. Next, it will try to use the First/Middle/LastName fields, if they are not null. Finally, it will use the Name field as a last resort. Keep in mind that this is not the FullName field, just the Name field.
I haven't tested this with an "Other" name, as I have my clients try not to use that list, but I would imagine it's similar to how Customers work.