From 1edf6584e56a5acfc98509232ba304d6f44274ff Mon Sep 17 00:00:00 2001 From: Dean Canlas <105271687+dean-canlas@users.noreply.github.com> Date: Mon, 17 Feb 2025 23:54:39 +0800 Subject: [PATCH 1/4] [LA-25015] Document Activities Create endpoint --- source/includes/_activities.md | 92 ++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/source/includes/_activities.md b/source/includes/_activities.md index 9b44676b2ec..373b9d4bcc9 100644 --- a/source/includes/_activities.md +++ b/source/includes/_activities.md @@ -206,3 +206,95 @@ filters[verb] | "started" | Return activity for a specific verb. See [verbs](#ve ] } ``` + +## Create an Activity + +##### NOTE: :construction: This endpoint is currently in beta and requires special access. Please raise a ticket on our Customer Portal to request access +---- + +Create an activty with a related [Item](#items) record and [Verb](#verbs). Please check to get an appropriate ID assigned to a specific verb. + +> Create a Activity record with an Item and Verb + +```shell +curl --location 'http://learnamptesting.lvh.me:3000/v1/activities' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer a3DWMdP8mmFRtvulvanOGgII7U1dVV8LZ9zr6jyCq4k' \ +--header 'Cookie: _learnamp_session_=aadc48937fec7520fd7cf3f7e55681e4' \ +--form 'user_id="1"' \ +--form 'verb_id="54"' \ +--form 'item_id="10"' +``` + +```ruby +module Learnamp + class Activities + include HTTParty + base_uri "#{ENV['BASE_URL']}#{ENV['API_PATH']}" + + attr_accessor :token + + def initialize(token) + @token = token + end + + def create(params) + response = self.class.post("/activities", { body: params, headers: headers }) + response.parsed_response + end + + private + + def headers + { + 'Authorization' => "Bearer #{token}" + } + end + end +end + +params_with_item_id = { + user_id: '1', + verb_id: '54' + item_id: '10', +} + +item_activity = Learnamp::Activities.new(token).create(params_with_item_id) + +params_with_external_id_item = { + user_id: '1', + verb_id: '54' + external_id: 'content_1234567890abcdef', +} + +external_item_activity = Learnamp::Activities.new(token).create(params_with_external_id_item) + +params_with_slug = { + user_id: '1', + verb_id: '54' + slug: 'content-slug-for-activity', +} + +activity = Learnamp::Activities.new(token).create(params_with_slug) +``` + +### Data in Body + +**Note:** The following parameters are mutually exclusive. It means you can only use one of other parameters to be a valid request. +- For the User the Activity belongs to: + - `user_id` + - `email` +- For the Item the Activity belongs to: + - `slug` + - `item_id` + - `external_id` + + +Parameter | Example value | Description (* required) +--------- | ------- | ----------- +user_id | 1 | ID of the User. +email | testuser@test.com | Email address of user. +verb_id | 54 | ID of the [Verb](#verbs) for this activity. *(\*)* +item_id | 1 | ID of the Item that is created within the Learn Amp platform. +slug | 'content-slug-for-activity' | Slug of an existing Item in the platform. +external_id | 1 or 'content_1234567890abcdef' | `source_id` of the Item that is in the Learn Amp platform but was created through the [Items](#items) create endpoint. \ No newline at end of file From 2941a601e3f207d221a7078e32ef32bc1197be1d Mon Sep 17 00:00:00 2001 From: Dean Canlas <105271687+dean-canlas@users.noreply.github.com> Date: Tue, 18 Feb 2025 00:04:09 +0800 Subject: [PATCH 2/4] [LA-25015] Add link for the Customer Portal --- source/includes/_activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/_activities.md b/source/includes/_activities.md index 373b9d4bcc9..5c4d3380eb7 100644 --- a/source/includes/_activities.md +++ b/source/includes/_activities.md @@ -209,7 +209,7 @@ filters[verb] | "started" | Return activity for a specific verb. See [verbs](#ve ## Create an Activity -##### NOTE: :construction: This endpoint is currently in beta and requires special access. Please raise a ticket on our Customer Portal to request access +##### NOTE: :construction: This endpoint is currently in beta and requires special access. Please raise a ticket on our [Customer Portal](https://learnamp.atlassian.net/servicedesk/customer/portal/1/user/login?destination=portal%2F1) to request access ---- Create an activty with a related [Item](#items) record and [Verb](#verbs). Please check to get an appropriate ID assigned to a specific verb. From 125956ab8ddba4e413f41e583df4b882ac37b62c Mon Sep 17 00:00:00 2001 From: Dean Canlas <105271687+dean-canlas@users.noreply.github.com> Date: Tue, 18 Feb 2025 00:09:28 +0800 Subject: [PATCH 3/4] [LA-25015] Add successful response payload --- source/includes/_activities.md | 62 ++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 3 deletions(-) diff --git a/source/includes/_activities.md b/source/includes/_activities.md index 5c4d3380eb7..daacd5bea33 100644 --- a/source/includes/_activities.md +++ b/source/includes/_activities.md @@ -217,7 +217,7 @@ Create an activty with a related [Item](#items) record and [Verb](#verbs). Pleas > Create a Activity record with an Item and Verb ```shell -curl --location 'http://learnamptesting.lvh.me:3000/v1/activities' \ +curl --location 'hhttps://testaccount.learnamp.com/v1/activities' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer a3DWMdP8mmFRtvulvanOGgII7U1dVV8LZ9zr6jyCq4k' \ --header 'Cookie: _learnamp_session_=aadc48937fec7520fd7cf3f7e55681e4' \ @@ -289,7 +289,6 @@ activity = Learnamp::Activities.new(token).create(params_with_slug) - `item_id` - `external_id` - Parameter | Example value | Description (* required) --------- | ------- | ----------- user_id | 1 | ID of the User. @@ -297,4 +296,61 @@ email | testuser@test.com | Email address of user. verb_id | 54 | ID of the [Verb](#verbs) for this activity. *(\*)* item_id | 1 | ID of the Item that is created within the Learn Amp platform. slug | 'content-slug-for-activity' | Slug of an existing Item in the platform. -external_id | 1 or 'content_1234567890abcdef' | `source_id` of the Item that is in the Learn Amp platform but was created through the [Items](#items) create endpoint. \ No newline at end of file +external_id | 1 or 'content_1234567890abcdef' | `source_id` of the Item that is in the Learn Amp platform but was created through the [Items](#items) create endpoint. + +> 201 Created - succesful response: + +```json +{ + "id": 225, + "activityable": { + "id": 10, + "name": "Content", + "shortDescription": null, + "type": "Item", + "url": "hhttps://testaccount.learnamp.com/en/items/content-slug-for-activity", + "addedBy": { + "id": 1, + "firstName": "First Name", + "lastName": "Last Name", + "jobTitle": "CTO", + "email": "firstlast.lastname@learnamp.com", + "timeZone": "London", + "language": "en", + "role": "viewer", + "hireDate": null, + "profileUrl": "hhttps://testaccount.learnamp.com/en/users/1", + "status": { + "status": "Confirmed", + "time": "On 4 Apr 23" + } + }, + "displayAddedBy": false, + "totalTimeEstimate": "< 5 mins" + }, + "user": { + "id": 1, + "firstName": "First Name", + "lastName": "Last Name", + "jobTitle": "Last Name", + "email": "firstlast.lastname@learnamp.com", + "timeZone": "London", + "language": "en", + "role": "viewer", + "hireDate": null, + "profileUrl": "hhttps://testaccount.learnamp.com/en/users/1", + "status": { + "status": "Confirmed", + "time": "On 4 Apr 23" + } + }, + "verb": "started", + "createdAt": "2025-02-17T16:08:29Z", + "expiredAt": null, + "result": "", + "completed": false, + "expired": false, + "score": null, + "totalTime": null +} +``` \ No newline at end of file From 58c3df89a2bdd9ac8cc939a2b010e8d6d68d0865 Mon Sep 17 00:00:00 2001 From: Dean Canlas <105271687+dean-canlas@users.noreply.github.com> Date: Tue, 18 Feb 2025 21:38:36 +0800 Subject: [PATCH 4/4] [LA-25015] Add failure responses --- source/includes/_activities.md | 45 +++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/source/includes/_activities.md b/source/includes/_activities.md index daacd5bea33..39db5aaa286 100644 --- a/source/includes/_activities.md +++ b/source/includes/_activities.md @@ -353,4 +353,47 @@ external_id | 1 or 'content_1234567890abcdef' | `source_id` of the Item that is "score": null, "totalTime": null } -``` \ No newline at end of file +``` + +> 400 Bad Request - validation errors: + +```json +{ + "error": "email is invalid, user_id, email are mutually exclusive", + "fullErrors": { + "email": [ + "is invalid" + ], + "userId": [ + "are mutually exclusive" + ] + } +} +``` +```json +{ + "error": "item_id, external_id are mutually exclusive", + "fullErrors": { + "itemId": [ + "are mutually exclusive" + ] + } +} +``` +```json +{ + "error": "item_id, slug are mutually exclusive", + "fullErrors": { + "itemId": [ + "are mutually exclusive" + ] + } +} +``` + +> 404 Not Found - unsuccessful response: + +```json +{ + "error": "Couldn't find Verb with 'id'=666" +}