Curriculum: integration options (REST, CSV, event-based)
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66aa351c287ce988bf12a493_Curriculum-p-130x130q80.png)
- In this lesson:
- 1Kick-off your project via CSV import
- 2Report on mails being sent
- 3Integration using the Curriculum REST API
- 4Curriculum REST OOAPI v5
- 5Event-based integration
- 6Report on integration (Exports)
- 7Report on integration (Request log)
- 8
- 9
- 10
- 11
Kick-off your project via CSV import
Curriculum allows the administrator to import data using csv files. The administrator can use the csv menu item from the administration menu to start the import:
- Select the type to import
Selecting the type will immediately show the details of the csv format to be used. - Specify the used separator (e.g. ; or ,)
- Upload the file (drop it on the file-box)
- Click on save to start the import
New elements are added, existing elements are changed based on the data imported. Only data offered via the csv is modified, data already defined in Curriculum and not provided via the csv will not be changed. This means data will not be deleted automatically and the csv could be used to import both ‘changed persons’ and ‘new persons’. Deletion of persons is not supported, this could be achieved by setting the end-date (logical delete).
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e033712_64d355dda8d2cbc9620e43aa_Screenshot%25202023-08-09%2520at%252010.58.05.png)
Scroll down to the end of the documentation to get an example with the csv header to use and an example data line.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e0336de_64d3562ad76a24fd0f58bb9f_Screenshot%25202023-08-09%2520at%252010.58.15.png)
The csv import offers support for the following data elements:
- Activity - The teaching and assessment activities (e.g. Lectures, practicals, written test) offered in the context of a module
- Advice - Advice given by commissions on studies.
- Appraisal - The module appraisal (examination) in case of assessment grouping
- Assessment - The assessment defines how a module is examined.
- Asset - The resources that can be used in an object.
- Assignment - Define the assignment of persons for organisation units
- Award_qualification - Define the relations between a qualification and study/specification.
- Cost_division - Cost divisions define how the costs are divided between organisational units.
- Description - Define descriptive text to an defined object, e.g. study, group, module, ...
- Field - Define custom field that add data elements to educational objects
- Faculty - The faculty is a group of university departments concerned with a major division of knowledge.
- Generated value - Import values that should be used in the 'unique' validation for objects. E.g. all historic study codes or module codes that has been given.
- Item - Define custom objects that add complex elements to educational objects
- Link - Links describe the relation between two objects, e.g. substitution rule, prerequisite, co-requisite, ..
- Meeting - Define activity sets (meetings) for activities.
- Method - The module methods defines the teaching methods provided by a module.
- Method_schema - Define the module method scheme (education) that specifies method grouping and choices.
- Module - Define module, which is a part of the education structure and defines the basic module information.
- Module_group - Define (module) groups, which is a part of the education structure and defines the educational components within a study, containing groups and/or modules.
- Objective - Define objectives (learning goals) assigned to a module, including the relation to assessment and subject
- Offering - Define offerings, that are the periods an educational object (study, module-group module) is available to students.
- Organisation - Define the organisational units, used to allocate staff
- Person - Define the persons / users that should have access to the system.
- Qualification - Define the qualifications used for allocating a degree to a program of study.
- Reference - Define reference table values. The reference table must be available!
- Relation - Define relations for an defined object, e.g. study, group, module, ...
- Resource - Define the resources (literature, software) that can be used in an object.
- Rule - Define rule (container) used to specify when certain requirements are reached, e.g. for graduation.
- Specification - Define specifications used specifies the generic, year independent structure of an object.
- Study - Define studies (programs of study), that specifies the offered program and its structure.
- Subject - Define subjects (learning outcome / skill) assigned to a study or module
- Task - Define the assigned non-educational tasks to a person assignment
- Value - The value import can be used to add or modify single attributes and value to a specific object. It can be considered as an additional option to set values on object level besides the standard option to immediately set values when importing the entire object without the effect of changing already defined relationships or other data to that object. In case changes are already made to the field imported, the changes made will be kept.
Report on mails being sent
The integration with the mail server is executed as part of the technical implementation. The administrator script menu offers the function Send test mail to technically test the correct implementation on a production environment to a self-defined receiver email address.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e0336db_64d35840d76a24fd0f5b510f_Screenshot%25202023-08-09%2520at%252011.11.13.png)
The non-production environments will send mails not to the actual email address of a user, but to a single (shared) mailbox to prevent accidentally sending mails to actual users.
If the mail integration is set-up and notifications have been defined to be send to the users from the processes, the sent notifications (emails) can be seen via the administrator menu Email.
The report provides an overview of all notifications sent, including if they are send successfully. On the top of the page an indication is shown that provides information on the queue used. The queue is used to limit the amount of mails send within time intervals, for instance for integration with office365 that may have limits on mails per minute, hour and/or day.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e0336ff_64d3594434cca03f2581e80c_Screenshot%25202023-08-09%2520at%252011.15.05.png)
The details of the mail (notification) sent can be inspected by clicking the notification.The subject and body shown contains the notification sent to the recipient, and will follow the recipient's 'language setting'.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e0336f0_64d3594b2e50ffc249b5c7d1_Screenshot%25202023-08-09%2520at%252011.15.26.png)
Integration using the Curriculum REST API
The Curriculum API is a REST/JSON based API used to build automated integration. The API provides both read, add, modify and logical deletion of data.
The full Curriculum API reference is available via: https://timeedit.readme.io
Use the navigation on the left and navigate to the Curriculum related information.
The direct link to for instance the Person service is: https://timeedit.readme.io/reference/saveperson_v2
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e03370c_66b0a358e7c6fca92343fc44_person_api.png)
The services can be tested from the URL.
Specific options are supported to steer the JSON message:
- expand - Option to manipulate the REST output. In the example the standard Study output will be extended with detailed Module-group (group) information.
Special cases are:- - - no extension at all, so a minimalistic JSON result will be created.
- * - the message will be maximal extended, leading to a very extensive message. This option should be used very carefully, and probably not on Study.
- system - define usage of the configured settings of a defined external system. For instance a (test) system that allows also unpublished information to be exchanged
Example: <base_url>/import/v2/study/MAABC123?year=2024&expand=group&system=SRS
Another useful tool for testing purposes is Postman. The API can be imported in Postman to generate the defined services and test the different calls to retrieve / post data.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e03370f_64d36193bd06b9d6d79445d5_Screenshot%25202023-08-09%2520at%252011.51.04.png)
At request:
- an example Postman project can be provided with sample request for (almost) all services and requests.
- an online explanation / training can be provided for the university developers to share knowledge and get into indepth technical details.
Curriculum REST OOAPI v5
Next to the standard Curriculum REST/JSON API there is also support for the OOAPI v5.
The OOAPI v5 is an open standard, information on the standard is available at the url: https://openonderwijsapi.nl/#/
The detailed definition of all services can be found at the url: https://openonderwijsapi.nl/specification/v5/docs.html
Curriculum fully supports the OOAPI V5, including the connectivity with eduXchange and RIO via the SURF eduHub.
As with the standard Curriculum API the OOAPI v5 can also be tested using Postman.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e0336fc_64d3624daa314f220c141fe8_Screenshot%25202023-08-09%2520at%252011.54.09.png)
Event-based integration
The mentioned API's are used to manage the data in Curriculum from an external source, or retrieve information from Curriculum using a request-reply mechanism.
Next to this integration architecture, Curriculum also supports the integration support where data is sent (published) from Curriculum to external systems based on events happening in the curriculum process(es).
In the guide on process configuration there is a section on Hooks. Hooks are defined as user configurable functions that can be executed from a process.
The hook used in integration is the hook named Export data.
Once fired, the Export data hook will sent data to the configured system for an educational object.
The hook configuration shown below just sends the data to the SRS.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0e73e8fab929371bc4317_66b0db8cf9335d30e344e1ea_Screenshot%25202024-08-05%2520at%252016.02.22.png)
In the process configuration the hook is defined to be fired at a specific moment.
The example shows the export to theSRS for the module should be executed once it is approved.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0e73e8fab929371bc42fc_66b0dc076f3265c4de928070_Screenshot%25202024-08-05%2520at%252016.04.47.png)
The configuration of the hook requests to specify the system. The selected system (configuration: External systems) is containing all the relevant connectivity information (endpoint, service, authentication).
The definition of a system is a two-step approach:
- Define the external system, endpoint, service, authentication, firewalls, etc. in close cooperation between customer integration department and TimeEdit
This definition is server based, to secure unauthorised access to this extremely vulnerable data. - Configure the system in Curriculum using the Administrator -> External systems menu option.
The example configuration has three external systems defined.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0e73e8fab929371bc4311_66b0dde25723ccf904e66279_Screenshot%25202024-08-05%2520at%252016.12.23.png)
Use the Add to define a new, or click on an already defined system to configure the external system.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0e73e8fab929371bc42ff_66b0de555990b715261f9dcb_Screenshot%25202024-08-05%2520at%252016.14.19.png)
The following options can be used to configure the system:
- Code - Unique name of the external system, used for display purposes and used as the unique identifier in the system configuration to technically define the external system (IP, authentication, ...)
- Description - Reason / description of the added system configuration
- Default - Indicator if this interface is the default, in which case it will automatically be selected if no receiving system is defined in the hook.
- Exportable - Indicator if this interface is allowed to receive 'finished and approved' data.
- Also show unpublished - Indicator if data not (yet) marked as published should be sent too. This options is particular handy for testing.
- Including removed - Indicator if deleted objects should also be in the output. This is for instance used for the integration with CORE to clearly mark deleted activity series.
- Include specification - Indicator if a specification should be sent before sending the data object. This is used for OOAPI, to be sure that the corresponding specification is sent before the actual program or course is sent.
- First sent to - Configure if the output should first be sent to another system. This can also be achieved using the combined hooks option in the hook configuration.
The output sent will have the exact format as the data retrieved performing a GET on that object using the REST API.
This allows for developing (and testing) your receiver endpoint by just putting a small step in front that retrieves the module and passes it to your receiver.
And once the receiver is in a good enough state, it can be connected directly to Curriculum and data can be sent from curriculum.
The default REST message sent via the publish mechanism is the condensed message format (unexpanded). This message format is standard used to have a lightweight data transfer that can be extended/expanded once needed.
The custom type configuration option is mainly used for manipulating the attributes of an object.
There is a tab that says Export types that allows configuration of the export relevant information for both external system and the object.
The example shows the configuration of the SRS integration.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0e73e8fab929371bc4309_66b0e159401346a0ff275462_Screenshot%25202024-08-05%2520at%252016.27.26.png)
The following options can be used to configure the system:
- Strategy - the approval strategy to be executed prior to sending. Strategies supported are:
- Automatic - Data will be sent as configured to the external system.
- Manual - Data is marked to be ready for the external system, but will be manually processed in the external system
- Ignore - Data is marked as 'sent', but will not be sent since the data is considered Curriculum only.
- Request - the Curriculum request method to be used:
- canonical:setStudy_v2 - use the standard curriculum REST API format. Based on the object, the option will change to setGroup and setModule.
- rio:submitV5 - use the RIO data format and specific rio submit methodology
- te:sendObject - used to sent data from Curriculum to Core using the Curriculum configured mapping
- Exclude pattern - Indicator if this interface is the default, in which case it will automatically be selected if no receiving system is defined in the hook.
- Expand fields - Option to manipulate the REST output. In the example the standard Study output will be extended with detailed Module-group (group) information.
Special cases are:- - - no extension at all, so a minimalistic JSON result will be created.
- * - the message will be maximal extended, leading to a very extensive message. This option should be used very carefully, and probably not on Study.
Report on integration (Exports)
The Administration -> Exports menu provides information on information sent using the publish (hooks) method.
There is a slight overlap with the Administration -> Request log functionality. That will show the initial call and the HTTP request status. So in fact a more technical level of information. So in case a message is sent and not found back in the Exports menu, it could well be that delivering the message has failed due to some technical error (e.g. unauthorized, unreachable, ...).
The Exports menu will show the message and its processing result by the receiver system. The RIO integrations are set-up as fire and forget integration based on the architectural requirements of RIO. The Request log will only notify if the message has been delivered (to the intermediate partner). The processing result from the receiving system is sent via a separate callback service by the receiving party. The Exports menu will combine the request and response (callback) in this case based on the correlation ID.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0e73e8fab929371bc432e_66b0e4d2c1b4ee237382323d_66b0a54ff9ab43956e033702_64d396fb6dcfc7085ae24a6f_Screenshot%2525202023-08-09%252520at%25252015.35.26.png)
Using the search and filter options offer various options to pinpoint the requested message information., f.i. select only the service requests that failed.
Filter options are:
- Search term - Search for a text in the message.
- System - Filter message sent to one of the configured external systems.
- Status - Specify the type of messages to be shown
- Completed
- Failed
- In progress
- Waiting for response - Creation time period - Specify the time window to search for/show the messages
Clicking on the item in the list will open the detailed information of the service request and response.
Where the Request Log provides technical status information (HTTP 400, 401, ...), the exports provide the functional error message.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e0336e7_64d39821ee07bdb96ec0e1f5_Screenshot%25202023-08-09%2520at%252015.43.46.png)
Report on integration (Request log)
The administrator menu option Request Log offers an overview of all API service requests (inbound and outbound) with Curriculum. It allows to inspect and investigate the working of the interfaces by giving in-depth information on the calls.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e0336e2_64d38bd817f434c4730971c7_Screenshot%25202023-08-09%2520at%252014.46.41.png)
Using the search and filter options offer various options to pinpoint the requested message information., f.i. select only the service requests that failed.
Filter options are:
- Action - Select messages that are sent/received via a specific end-point. Depending on the configuration the Actions may vary. As part of the implementation and definition of the integrations the naming will be defined and exchanged with the (system) administrator.
- Entity - Search for the messages of a specific object (faculty, study, module group, module, person, ...)
- From - Define the start date from which the messages will be searched.
- To - Define the end dat till which the messages will be searched.
- Status - Specify the type of messages to be shown
- All
- Success
- Error
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e0336f3_64d38be8231f1fccca163593_Screenshot%25202023-08-09%2520at%252014.49.25.png)
Clicking on the item in the list will open the detailed information of the service request and the exchanged information.
![](https://cdn.prod.website-files.com/6262657cb68f4978d6d20e73/66b0a54ff9ab43956e033709_64d38bf2fb1522ec915aa241_Screenshot%25202023-08-09%2520at%252014.49.37.png)
By clicking on the </>JSON, </>XML button or (raw) link the detailed message information sent and received will be shown.
You can just copy the message to an editor of your choice that will render and display the JSON / XML in a readable structure to investigate either the message sent or the message received.