diff --git a/source/includes/_activities.md b/source/includes/_activities.md index 9b44676b2ec..39db5aaa286 100644 --- a/source/includes/_activities.md +++ b/source/includes/_activities.md @@ -206,3 +206,194 @@ 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](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. + +> Create a Activity record with an Item and Verb + +```shell +curl --location 'hhttps://testaccount.learnamp.com/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. + +> 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 +} +``` + +> 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" +}