External payment integration

Scenario description

The following document describes a possible api integration for a third party that handles the payments on their own server but wants to automate the process of enrolling new users.

Flow description

The guide assumes that the courses are already created in knolyx and all the necessary configuration regarding feedback, diplomas, gamification is already done.

Extract the course id from knolyx;
1. the course id is need to assign the user to the correct course
Manually create a workgroup for that course;
1. a workgroup is a collection of users
Create a rule for that course with the workgroup
1. a rule in knolyx is an entity that allows an admin to select witch persons have access to the course
2. a rule can specify access to workgroups, departments and individual users
3. a rule describes what diploma to use / what feedback and other information
4. a rule can be private (access restricted using 3.2) or public (anyone with access to the platform can access the course)
5. a rule has a start date and an end date (any date outside the interval will now allow the student to take the course)
Manually and the necessary feedback / diploma on that rule
1. can’t be done with the api
After a course is bought:
1. provision user
  1. the api will check if the user does not have an account and creates it
  2. Nothing happens if the account already exists
2. add the student to the workgroup
  1. this will give the student access to the course (the workgroup needs to be assigned to a rule on the course, see Flow 3.)

Steps 1 through 4 are needed only once for each course.

1. Extract the course id from knolyx

Get course list paged GET /public/api/v1/course?pagination.page=0&pagination.size=20

The api will return a json list, with objects that contain an id and a title. For a given course title, copy the course id.

2. Manually create a workgroup for that course

Ask an admin to create a workgroup with the name of the course.

Get workgroup list paged GET /public/api/v1/workgroup

The api will return a json list, with objects that contain an id and a name. For a given workgroup name, copy the workgroup id.

3. Create a rule for that course with the workgroup

Create a rule using 3.2. Given than the course already exists, first the rules should be retrieved using 3.1, a new rule having the shape of the example down below be added and saved using 3.2. In case future modifications of the rule should be done using the api we recommend setting the name as something computer friendly (ex.: PAYMENT_INTEGRATION_COURSE_{courseId}). Later, the rule can be identified using that name.

Example:

[
  {
    "id": 2296,
    "name": "Rule name",
    "type": "PUBLIC | PRIVATE", 
    // for this scenario use case, always private.
    // !!!Public will give access to all students on knolyx
    // start date and end date in UTC timezone with format:
    // year-month-day hour:minutes
    "startDateTime": "2020-05-06 21:00:00",
    // start date and end date in UTC timezone with format: 
    // year-month-day hour:minutes
    "endDateTime": "2022-12-30 22:00:00",
    // Note:!! startDate and endDate are required.
    // If the course is bought indefinetly,
    // set a 50 year timeframe for example
    "restrictions": {
      "minimumTime": false, // should be false
      "browseOrder": "anyOrder" // should be any order
    },
    "associations": {
      "WORKGROUP": [
        workgroupId
      ]
    },
    "action": "WORKGROUP" // ignore action field
  }
]

3.1 Get rule GET /public/api/v1/business-rule/course/{{courseId}} The GET request will return an array of applied rules to a course.

3.2 Save rule POST /public/api/v1/business-rule/course/{{courseId}}

The post will apply the changes in rules. The old payload should be passed modified to the POST request. For example, to remove a workgroup from the list, we GET the rules of the course and POST the new rule list.

[
  previous rules here...,
  {
    "id": 2296,
    "name": "rule name modified",
    "type": "PRIVATE",
    "startDateTime": "2020-05-06 21:00:00",
    "endDateTime": "2022-12-30 22:00:00",
    "restrictions": {
      "minimumTime": false,
      "browseOrder": "anyOrder"
    },
    "associations": {
      "WORKGROUP": [
        24792,
        24793
        // workgroup removed from here
      ]
    }
  }
]

If the id is present in the rule, the api will modify the existing rule. If no id is given, a new rule is created. If a rules is removed from the list, a POST action without it will delete it.

4. Manually and the necessary feedback / diploma on that rule

Get in touch with an admin to make the necessary changes. The diploma will be set on the rule created at step 3.

5. After a course is bought

5.1 provision user

Provision user endpoint POST /public/api/v1/user/provision

The endpoints allow to create and edit basic user information. If the user does not exist, the response status will be 201 (created) and an on-boarding email is sent to the user. If the user exists, the response status will be 200 OK, no email will be sent and the changed fields will be persisted.

Example body

{
  "firstName": "Jon",
  "lastName": "Doe",
  "email": "jon.doe@knolyx.com",
  "gender": "NON-BINARY"
  }

All fields besides gender are required. If gender is omitted, a default value of NON-BINARY is set. Gender values allowed: NON-BINARY | MALE | FEMALE.

5.2 add the student to the workgroup

Add student to workgroup

PUT /public/api/v1/workgroup/{workgroupId}/member/{user-email}/

Body

{ "removalDate": "2024-05-04 14:30:00" }

The removal date is the date when the student is removed from the workgroup (and by extension loses access to the course). If no removal date is needed, the value should be null.

The removal date has the format yyyy-MM-dd HH:mm:ss and should be in UTC time.

If the request was successful then a status code of 200 will be returned and a json of format:

{
  "email": "{user-email}"
}

To remove a student form the workgroup, repeat the above call with DELETE.