Desire2Learn Valence API Creating and updating sections?

Question

I am working on integration with our university's SIS system and am stumbling a bit with the documentation related to creating and updating sections. http://docs.valence.desire2learn.com/res/enroll.html#Section.SectionData

I can use the route PUT /d2l/api/lp/(version)/(orgUnitId)/sections/ to create a default section named Section 1 with section code sec1 however when I try to update it or add an additional section with the routes: PUT /d2l/api/lp/(version)/(orgUnitId)/sections/(sectionId) (with the sectionId retrieved from my previous PUT) or POST /d2l/api/lp/(version)/(orgUnitId)/sections/

I am using the following block for my json data:

{
  "Name": "Section 1d",
  "Code": "Dan 101",
  "Description": {
    "Text": "",
    "Html": ""
  }
}

What am I missing in the syntax?

Thank You

Answer 1

It looks like your routes and your request are okay. Only one small change with the route. You need to use the RichTextInput field that is described in the documentation D2L Conventions

Basically instead of:

"Description": {
   "Text": "",
   "Html": ""
}

You need:

"Description": {
   "Content": "",
   "Type": "" (Either Text or Html)
}

Answer 2

The way you use the Valence Learning Framework API to create sections for course offerings is idiosyncratic. Assume you start with a blank course, that has no descendant org units (no sections, no groups, nothing):

GET /d2l/api/lp/1.3/orgstructure/113459
> {"Name": "Extensibility 106",
   "Identifier": "113459", 
   "Type": {"Name": "Course Offering", 
            "Code": "Course Offering",
            "Id": 3},
   "Code": "EXT-106"}

GET /d2l/api/lp/1.3/orgstructure/113459/children
> []

Initialize course with section properties. The first thing you have to do is define the section properties for the course offering: what kind of sections do you want to create under the course offering? To create the section properties for the course offering, you use a SectionPropertyData block; here's one that says "I want this course to have 10 sections and to auto-enroll the students, randomly, into these sections" (EnrollmentStyle 2 corresponds to NumberOfSectionsAutoEnrollment):

{"AutoEnroll": true,
 "EnrollmentQuantity": 10,
 "EnrollmentStyle": 2,
 "RandomizeEnrollments": true}

Now, to initialize the course with these settings, and have the first default section(s) created, we PUT that block to this route:

PUT /d2l/api/lp/1.3/113459/sections/
> [{"SectionId":113460,
    "Name":"Section 1",
    "Description":{"Text":"","Html":""},
    "Enrollments":[]},
   ...
   {"SectionId":113469,
    "Name":"Section 10",
    "Description":{"Text":"","Html":""},
    "Enrollments":[]}
  ]

Notice that with this call, we've now created 10 sections as children of this course offering, and the back-end service has automatically generated names (and codes) for them.

Add a new section after the fact. Now suppose we want to add an eleventh section to this course. First, we need to use a SectionData block for the new section's properties:

{"Name": "Section 11",
 "Code": "Sec11",
 "Description": {"Content": "New Section Descr.", "Type": "Text} }

(Note: When you form this block to create the new section you have to use a RichTextInput type structure for the Description property. When you get the properties for a section back from the service, it writes the description using the RichText property instead. This is a common sticky point for devs new to the framework)

Then, you POST that block to this route:

POST /d2l/api/lp/1.3/113459/sections/
> {"SectionId":113470,
   "Name":"Section 11",
   "Description":{"Text":"Description","Html":""},
   "Enrollments":[]}

You'll get back the properties for the newly created section.

Summary. So, "why PUT and then POST"? Yes, it is a bit confusing, but think of it this way:

1. The first use, of PUT, is to update the "section properties" attribute for a course offering (as a consequence, when a course offering's section properties are initially defined, as a side effect, the back-end creates the section org units needed to go along with those new settings).

2. The second use, of POST, is to create a new org unit (a new section), and assign it to the course offering.