<?xml version="1.0"?>
<rss version="2.0"><channel><title>Guides: Guides</title><link>https://educloud.ist.com/guides/ss-12000/?d=1</link><description>Guides: Guides</description><language>en</language><item><title>Fetching teachers</title><link>https://educloud.ist.com/guides/ss-12000/fetching-teachers-r4/</link><description><![CDATA[
<p><img src="https://educloud.ist.com/uploads/monthly_2022_02/board-4444443.jpg.ee9c331f6606ce83552695aa914962db.jpg" /></p>
<p>
	The SS12000 specification don't have a pure teacher or student endpoint. So how can you receive a list of teachers?<br />
	However, the specification do define endpoints for persons working in a school. Each teacher should have an assigned duty, and <a href="https://educloud.ist.com/api-docs/#tag/Person/paths/~1duties/get" rel="">there is an endpoint for duties</a>.
</p>

<p>
	<span style="font-size:20px;">Fetching duties</span><br />
	In this guide we'll use Postman to test our requests. You can download and use our <a href="https://github.com/ist-group/educloud-examples/releases/download/1.0.1/EduCloud.-.SS12000.postman_collection.json" rel="external nofollow">Postman collection</a> to easily get started working with educloud in postman. If you're new to postman you can learn how to import it in the <a href="https://educloud.ist.com/guides/getting-started/importing-our-postman-collection-r3/" rel="">"Importing our Postman Collection" guide</a>.
</p>

<p>
	Now, to fetch duties we simply make a request to <a href="https://api.ist.com/ss12000v2-api/source/SE00100/v2.0/duties" rel="external nofollow">https://api.ist.com/ss12000v2-api/source/SE00100/v2.0/duties</a>.
</p>

<p>
	<a class="ipsAttachLink ipsAttachLink_image" data-fileext="png" data-fileid="16" href="https://educloud.ist.com/uploads/monthly_2022_02/image.png.750f73410988c2059b054e184fbbd315.png" rel=""><img alt="fig. 1 - Receive a list of duties" class="ipsImage ipsImage_thumbnailed" data-fileid="16" data-ratio="86.61" style="width:866px;height:auto;" width="866" data-src="https://educloud.ist.com/uploads/monthly_2022_02/image.thumb.png.dc783143d83151a4da69a12702767576.png" src="https://educloud.ist.com/applications/core/interface/js/spacer.png" /></a>
</p>

<p>
	This returns a list of every duty we have. We can see what school / organisation this duty belongs to, when it started and so on.<br />
	There is also the field dutyRole which defines what kind of work the duty represents.<br />
	In the <a href="https://educloud.ist.com/api-docs" rel="">API documentation</a> you can see that there is a parameter we can use that lets us filter the results to only include those with the duty role of teacher (and since SS12000 is a swedish standard it's called "lärare"):
</p>

<p>
	<img alt="fig. 2 - Show available options for dutyRole filters" class="ipsImage ipsImage_thumbnailed" data-fileid="13" data-ratio="12.94" style="width:912px;height:auto;" width="912" data-src="https://educloud.ist.com/uploads/monthly_2022_02/image.png.279211f365348bf0025fcb083b9fe8cd.png" src="https://educloud.ist.com/applications/core/interface/js/spacer.png" />
</p>

<p>
	So what we need to do then is to add dutyRole as a query param, like so: <a href="https://api.ist.com/ss" rel="external nofollow">https://api.ist.com/ss</a>12000v2-api/source/SE00100/v2.0/duties?dutyRole=Lärare - Let's try it and see what kind of result we get back:<span> </span>
</p>

<p>
	<a class="ipsAttachLink ipsAttachLink_image" data-fileext="png" data-fileid="18" href="https://educloud.ist.com/uploads/monthly_2022_02/image.png.05e9b48505b605fef90f8e96bc7fed8e.png" rel=""><img alt="fig 3 - duties filtered on the teacher dutyRole" class="ipsImage ipsImage_thumbnailed" data-fileid="18" data-ratio="86.61" style="width:866px;height:auto;" width="866" data-src="https://educloud.ist.com/uploads/monthly_2022_02/image.thumb.png.02fb2a9d9df3fdec435aaa3e4042b319.png" src="https://educloud.ist.com/applications/core/interface/js/spacer.png" /></a>
</p>

<p>
	If you compare the two you'll see that the first visible object has changed from "Annan Personal" to "Lärare", meaning that our filter was successful.<br />
	What about the personal information about the teacher such as first name or their email addresses?<br />
	In order to get that we need to add one more parameter to our request.
</p>

<p>
	 
</p>

<p>
	<span style="font-size:20px;">Expanding the result with person</span>
</p>

<p>
	If we jump back to the documentation one last time we can see that the duties endpoint has another param that we can add to our request, which is the <em>expand</em> key. The expand lets us send in a string or a list of string to expand our request with additional data that the entity we're requesting might hold.
</p>

<p>
	<img alt="image.png.17a79abea4d714066148c394688ab212.png" class="ipsImage ipsImage_thumbnailed" data-fileid="14" data-ratio="11.44" style="height:auto;" width="918" data-src="https://educloud.ist.com/uploads/monthly_2022_02/image.png.17a79abea4d714066148c394688ab212.png" src="https://educloud.ist.com/applications/core/interface/js/spacer.png" />
</p>

<p>
	In the duty case shown below we have the option to expand on "person" which will include a data from the person entity as an embed.
</p>

<p>
	<a class="ipsAttachLink ipsAttachLink_image" data-fileext="png" data-fileid="20" href="https://educloud.ist.com/uploads/monthly_2022_02/image.png.3419ce829532ac86ed2fa51e2ca97c74.png" rel=""><img alt="All data that we get by using the expand key will be available via the _embedded key on the response" class="ipsImage ipsImage_thumbnailed" data-fileid="20" data-ratio="86.61" style="width:866px;height:auto;" width="866" data-src="https://educloud.ist.com/uploads/monthly_2022_02/image.thumb.png.2a5d1a65304505e5dd2f03d1223c2bbd.png" src="https://educloud.ist.com/applications/core/interface/js/spacer.png" /></a>
</p>

<p>
	All data that we get by using the expand key will be available via the _embedded key on the response.
</p>

<p>
	And that's it! Now we've managed to get all the teachers from a specific customer from SS12000.<br />
	If you want to filter the data further, such as fetching teachers from a specific school you can use the "organisation" query param as well.
</p>

<p>
	If you have any questions regarding this you're most welcome to ask them in <a href="https://educloud.ist.com/forums" rel="">the forums</a>.
</p>
]]></description><guid isPermaLink="false">4</guid><pubDate>Tue, 01 Feb 2022 12:21:21 +0000</pubDate></item><item><title>Paginating results</title><link>https://educloud.ist.com/guides/ss-12000/paginating-results-r5/</link><description><![CDATA[
<p><img src="https://educloud.ist.com/uploads/monthly_2022_05/book-5077895.jpg.209f7236ea9b1482aa1ffb1908098494.jpg" /></p>
<p>
	Schools holds a lot of data.<br />
	A municipality holds a lot of students (at the time of this writing Stockholm has <a href="https://skolkollen.se/stockholm-kommun/gymnasium" rel="external nofollow">41796</a> registered gymnasium students, Gothenburg has <a href="https://skolkollen.se/goteborg-kommun/gymnasium" rel="external nofollow">23399</a>), and each student gets grades in 10 subjects (just to make it easier to count).<br />
	Fetching all the grades based on these two examples could potentially mean well over 100 000 grades. The size of one grade weighs about 1Kb, which would mean that the result would be 100 Mb.<br />
	That's a lot of data to download before being able to parse it. When the client make that request it needs to wait for the entire result to come back before it could handle the data, resulting in that the client times out before it can even get started.<br />
	You could see it as fetching water from a well. If you need 180 liters of water it's hard to take one big tank to the well by hand, fill it up and drag it back home.<br />
	Instead you use smaller buckets and run back and forth to the well until you've got everything you need. That's why it's better to use paginated results.
</p>

<p>
	How do I paginate our SS12000 data?
</p>

<p>
	Paginating our SS12000 data is very easy.<br />
	Use the query parameter <strong>limit</strong> in the request (<span><a href="https://api.ist.com/ss12000v2-api/source/SE00100/v2.0/grades?limit=1)" rel="external nofollow">https://api.ist.com/ss12000v2-api/source/SE00100/v2.0/grades?limit=1)</a></span>.<br />
	That will populate the the attribute <strong>pageToken</strong> in the response.
</p>

<p>
	<a class="ipsAttachLink ipsAttachLink_image" data-fileext="png" data-fileid="62" href="https://educloud.ist.com/uploads/monthly_2022_05/image.png.0599a4706dfdeeaee08a846899f9790f.png" rel=""><img alt="limit and pageToken example" class="ipsImage ipsImage_thumbnailed" data-fileid="62" data-ratio="91.24" style="width:822px;height:auto;" width="822" data-src="https://educloud.ist.com/uploads/monthly_2022_05/image.thumb.png.b240cb2d10176c595f681b3285dc48b1.png" src="https://educloud.ist.com/applications/core/interface/js/spacer.png" /></a>
</p>

<p>
	In this example I'm just using limit=1 but that is obviously just for this example.<br />
	In a real scenario a suitable page size would be between 1000 and 2000 items. It might be self-explanatory, but how many you should get in a single request all boils down to the size of the item (grades as mentioned above is 1kb per item, so 1000 grades would mean 1Mb per chunk).<br />
	Personally I would try and stick to around 1Mb.<br />
	 Anyway, the next time I do my request I just use that pageToken as a parameter to get the next page of data. When you have the pageToken you don't need the limit anymore.
</p>

<p>
	When you reach the last page of the book (well, rather collection) the pageToken will be empty.<br />
	That way you know you're done.<br />
	 
</p>
]]></description><guid isPermaLink="false">5</guid><pubDate>Fri, 13 May 2022 06:59:06 +0000</pubDate></item></channel></rss>
