Introduction
As of February 2, 2021, the Contribute functionality and the associated asset editing and expert peer review processes will be enhanced in order to offer a completely revamped way to contribute and manage learning assets in your platform. The name of the functionality changes from Contribute to Share Content, and the same change applies to the name of the page reachable from the user menu.
This enhanced and improved functionality introduces important changes in your platform and the new sharing process improves the security and the privacy of content shared by users in the platform. Moreover, the user interface of the areas where users share and edit assets (informal content), experts review and publish them, and Superadmins manage and monitor the process have been redesigned in line with the new behavior of the functionality and the new platform layout.
This article lists the changes introduced by this feature enhancement and lists the APIs that have been changed and developed for this new feature.
New User Interface and Experience
The current user interface restyling offers an easier and more intuitive way to share, edit, review and manage assets in your platform, and the platform areas where these actions are performed have been redesigned in line with the new platform layout.
With the new Share Content experience, the user is now able to choose which type of content to share, complete the entire configuration (sharing options included) and then complete the action directly from the right panel.
The edit asset experience for users has been redesigned and split into two dedicated tabs. The first one shows general information about the asset and the second enables the user to see at a glance all the people and channels he or she shared the asset with.
The expert peer review process has been enhanced and is now more user friendly, as fully described in the dedicated chapter below in this document. As for the assets management by Superadmins, a dedicated tab in the Channel Management menu has been added, where admins can see in one place all the info about the assets shared in their platforms
Furthermore, on the Discover, Coach & Share Settings page, the Private Asset section has been removed (the concept of public or private assets does not exist anymore) and instead the new Sharing Permissions option has been added to allow Superadmins to configure asset sharing permissions for their users.
Finally, a new widget named Share Content has been added, showing the content shared by users in the platform and allowing users to upload and share new content.
Deprecation of Private/Public Status for Assets Visibility
How does it work now?
In the current Contribute functionality, when a user publishes an asset, he or she needs to define a status for asset visibility: public or private.
A public asset can be shared with (and published into) channels. After a user publishes the asset, he or she can then invite other users or channels to watch it. Remember that a user can only invite other users already having visibility on the channels where the asset is published.
A private asset is only visible to the user who shares the asset and to the users he or she invites to watch the asset. If the asset visibility is set to Private, the asset can be shared with specific individual people using the Invite to Watch functionality. Any user in the whole platform can be invited to watch a private asset, without any visibility rule.
How will it work with the new functionality?
With the new Share Content functionality, the concept of public or private assets does not exist anymore. When sharing content, the user can choose between two options:
- Sharing the content with channels and/or people;
- Saving the content only to him or herself. The content is saved on the user’s My Channel page, and it will be visible only to himself or herself and will not appear in the search results of other users.
An asset can be shared with channels and people at the same time and in the same panel.
In the Discover, Coach & Share Settings admin menu, the Superadmin can configure the sharing options which are available to the user. The new Sharing Permissions setting allows Superadmins to choose between four options:
- The user can share content with both channels and other people;
- The user can share content with channels only;
- The user can share content with channels and people belonging to the same branches;
- The user can share content with channels and people belonging to the same branches and sub-branches.
If the Extended Enterprise is enabled in the platform, only the two following options are available:
- The user can share content only with channels;
- The user can share content with channels and people belonging to the same subdomain.
For the platforms where the option to allow users to upload private assets is currently disabled (Private Assets section in the Discover, Coach & Share Settings menu, removed in the new functionality as explained in the section above), the new Sharing Permissions setting is set to Share content with channels only, allowing users to share assets only with channels. For the platforms where the Private Assets option is currently enabled, the new setting is set to Share content with channels and people (or Share content with channels and people in the same subdomain if the Extended Enterprise app is active in the platform), allowing users to share assets both with channels and people.
Another enhancement is that from the new Assets tab in the Channel Management menu, the Superadmin can easily view, for each asset, how many channels and people the asset has been shared with.
Moreover, for users, the new sharing options are more intuitive and easier to understand than the concept of private and public assets. They are also easier to manage by Superadmins, thanks to the addition of the new Sharing Permissions setting on the Discover, Coach & Share Settings menu and the new Assets tab on the Channel Management menu.
Expert Peer Review
How does it work now?
In the current functionality, when an expert needs to approve an asset so that it can be published in a channel, he or she opens the asset page, edits it and uses the Unpublish - Publish toggle to approve and thus publish the asset just reviewed.
When the expert reviews an asset, the Related Expert chat box designed for the communication between the user who has contributed the asset and the expert who needs to review it is scarcely used (or not used at all, since experts and contributors prefer other ways to communicate), so it will no longer be available in the new functionality.
The expert approval allows the publication of the asset in all of the channels where the user requested to publish the asset, not only in the channel or channels where he or she is an expert.
How will it work with the new functionality?
With the new functionality, when an expert needs to approve an asset, once on the asset page, he or she will find the Approve Asset and Reject Asset buttons at the top of the page.
If the expert approves the asset, it will be published in the channels where the user chose to share it and for which he or she is an expert.
If the expert rejects the asset, it won’t be published in the channels where the user chose to share it and for which he or she is an expert. Keep in mind that this asset may be published in a channel where another user is an expert if the expert of that channel approved the publication in the channel he or she manages as an expert. The expert approval can only allow the publication of the asset in the channel where he or she is an expert.
The new behavior for expert peer review is more intuitive, and allows each expert to closely monitor the publication of the assets in the channels managed by him or her.
Content Re-sharing by Users
How does it work now?
With the current functionality, any user who has been invited to watch a private asset can then send an invitation to watch the asset (and as a consequence give permissions to view it) to any other users in the whole company. The only exception is when the Extended Enterprise app is active in your platform.
How will it work with the new functionality?
With the new functionality, if a user has been invited to watch an asset, he or she can only send an invitation to watch it to the users that already have the permissions to view the asset. Only the platform Superadmin and the user who uploaded the asset are able to extend the asset’s visibility permissions, by adding new channels or people from the asset’s edit page.
The Superadmin and the user who uploaded the asset into the platform can now easily control and manage the assets sharing activities, without the risk of uncontrolled sharing.
Email Address of the User Invited to Watch
How does it work now?
In the current functionality, when a user invites other users to watch an asset, the email address of the users that can be invited is shown together with their usernames.
How will it work with the new functionality?
For privacy reasons, users' emails cannot be displayed anymore neither when inviting to watch nor when sharing content with other users or channels. Only usernames are shown.
Viewing Invite to Watch Statistics
How does it work now?
At present, when a user edits an asset, he or she can also select the Analytics button in the top right corner of the asset’s edit page to view data and statistics about the invitations sent to watch the asset.
How will it work with the new functionality?
With the new edit asset experience, the statistics page on the Invite to Watch feature will no longer be available from the asset’s edit page.
Users will be able to view data on the views of the asset they shared (number of views and date) directly from the Shared with tab on the asset’s edit page, while Superadmins can access statistics from the Asset Summary report reachable from the reports menu.
Changed APIs
The Changed APIs table lists all of the APIs that have been changed with the new Share Content functionality and the associated new processes for asset editing and expert peer review. Three of the following are breaking changes.
| API Description | API Verb | API URL | Changes |
|---|---|---|---|
| Get ShareApp settings | GET | /share/v1/settings | Added the optional parameter “share_to_people” to define the sharing permissions |
| Update ShareApp settings | PUT | /share/v1/settings | Added the optional parameter “share_to_people” to define the sharing permissions |
| Returns assets available in the platform | GET | /share/v1/admin/assets | Added the item "people_assignment_count" in the response. Added the item “included_in_channels” in the response. It represents the list of channels assigned to the asset. Breaking Change - Previously, if the asset visibility was set as private and the asset was not assigned to any channels, the item “channels_assignment_count” was not returned. With the new Share Content functionality, if the asset is not assigned to any channels, the item “channels_assignment_count” will return value “0”. In general, the number of channels to which the asset is assigned is returned. |
| Update asset | PUT | /share/v1/assets/{id_asset} | Added 2 optional input parameters: "file_name" and "original_file_name" |
| Asset view | GET | /share/v1/assets/{id_asset} | Added the optional input parameter "show_users" = true. If passed, the list of users invited to watch the asset is returned. |
| Retrieve all invitable users for a specific asset | GET | /share/v1/assets/{id_asset}/invitations/users | The list of users that can be invited is now calculated based on the Sharing Permissions setting configuration. Breaking Change - The parameter “search” is now mandatory for security requirements. |
| Retrieve invite to watch initial information | GET | /share/v1/assets/{id_asset}/invitations/suggestions | The list of users that can be suggested for invitation will now be calculated based on the Sharing Permissions setting configuration |
| Create a new contribution of type image | POST | /share/v1/image | New peer review logic applied |
| Create a new contribution of type link | POST | /share/v1/link | New peer review logic applied. Added the new parameter “content_type” to set the type of link. The type can be: links, docs, sheets or slides. |
| Create a new contribution of type video link for Vimeo, Youtube, Wistia | POST | /share/v1/videolink | New peer review logic applied |
| Update asset | PUT | /share/v1/assets/{id_asset} | New peer review logic applied |
| Create a new Course | POST | /learn/v1/courses | New peer review logic applied |
| Update specific Course | PUT | /learn/v1/courses/{id} | New peer review logic applied |
| Create a new contribution of type video | POST | /share/v1/video | New peer review logic applied. Breaking Change - Previously, the parameter “thumbnail_url” was ignored. With the new Share Content functionality, if this parameter is passed (optional), the thumbnail is set as default for the asset. |
| Asset View | GET | /share/v1/assets/{id_asset} | Added the “peer_review” item in the response. It represents the status of the asset in a specific channel where expert’s review is needed. |
| Add a custom thumbnail for a given asset | POST | /share/v1/assets/{id_asset}/thumbnails | Added the optional parameter “not_default” in order to decide if a thumbnail is used by default |
| Create a new asset | POST | /share/v1/assets | Added the “tags” parameter to associate tags to the asset |
| Send invite to watch invitations | POST | /share/v1/assets/{id_asset}/invitations | Previously, if this API was used to invite again a user already invited to watch an asset, the API returned an error. Now, it is possible to invite the same user more than once, and no error is returned. |
| View Asset assigned Channels | GET | /share/v1/assets/{id_asset}/channels | Added the new parameter “search_text” to filter results by name |
| Retrieves the assets of the channel | GET | /share/v1/admin/channels/{id_channel}/content | New peer review logic applied to the asset status |
New APIs
The New APIs table lists the APIs available for the new Share Content functionality and the associated new processes for asset editing and expert peer review. These APIs will be fully operational starting on February 2, 2021.
| API Description | API Verb | API URL |
|---|---|---|
| Creates an association between the assets and the channels | POST | /share/v1/admin/channels/assets |
| Retrieves the users who have been invited to watch an asset | GET | /share/v1/assets/{id_asset}/users |
| Removes the associations between a user and an asset | DELETE | /share/v1/admin/user/{id_user}/asset/{id_asset} |
| Get link metadata and image | GET | /share/v1/link/meta |
| Checks if a specific Screen-Recording video uploaded as asset exists. | GET | /share/v1/screenrecorder/upload/status |
| Approve an asset in the channels you are an expert for | POST | /share/v1/assets/{id_asset}/approve |
| Reject an asset in the channels you are an expert for | POST | /share/v1/assets/{id_asset}/reject |
| Delete a user invitation | DELETE | /share/v1/assets/{id_asset}/invitations/{id_user} |
| Create a new contribution of type document | POST | /share/v1/document |
| Edit a contribution of type video | PUT | /share/v1/video/{id_asset} |
| Edit a contribution of type document | PUT | /share/v1/document/{id_asset} |
| Create a new contribution of generic type | POST | /share/v1/generic |
For each new API, the list of parameters is detailed in the following sections.
Creates an association between the assets and the channels
POST /share/v1/admin/channels/assets @parameter assets [array(integer), required] : The assets to associate to channels @parameter channels [array(integer), required] : The channels to be associated to assets
Retrieves the users who have been invited to watch an asset
GET /share/v1/assets/{id_asset}/users @get id_asset [integer, required] : The ID of the asset @parameter sort_attr [enum(user_id, username, fullname), optional] @parameter sort_dir [enum(asc, desc), optional] : The sorting direction: asc = ascending, desc = descending. Default: asc @parameter page [integer, optional] : The page to return. Default: 1 @parameter page_size [integer, optional] : The maximum number of results per page. Default: platform dependant
Removes the associations between a user and an asset
DELETE /share/v1/admin/user/{id_user}/asset/{id_asset} @get id_user [integer, required] : The ID of the user @get id_asset [integer, required] : The ID of the asset
Get link metadata and image
GET /share/v1/link/meta @parameter url [string, required] : The URL from which info are extracted
Checks if a specific Screen-Recording video uploaded as asset exists
GET /share/v1/screenrecorder/upload/status @parameter filename [string, required] : The name of the file
Approve an asset in the channels you are an expert for
POST /share/v1/assets/{id_asset}/approve @get id_asset [integer, required] : The ID of the asset
Reject an asset in the channels you are an expert for
POST /share/v1/assets/{id_asset}/reject @get id_asset [integer, required] : The ID of the asset
Delete a user invitation
DELETE /share/v1/assets/{id_asset}/invitations/{id_user} @get id_asset [integer, required] : The ID of the asset @get id_user [integer, required] : The ID of the user
Create a new contribution of type document
POST /share/v1/document @parameter url [string, required] : The URL of the document @parameter title [string, required] : The title of the document @parameter description [string, required] : The description of the document @parameter original_filename [string, required] : The original filename of the document @parameter thumbnail_url [string, optional] : The URL of the thumbnail @parameter channels [array(integer), optional] : The list of IDs of the channels where the document is published @parameter tags [array(string), optional] : The list of tags assigned to the document
Edit a contribution of type video
PUT /share/v1/video/{id_asset} @get id_asset [integer, required] : The ID of the asset @parameter url [string, required] : The URL of the video @parameter title [string, required] : The title of the video @parameter description [string, required] : The description of the video @parameter original_filename [string, required] : The original filename of the video @parameter thumbnail_url [string, optional] : The URL of the thumbnail @parameter channels [array(integer), optional] : The list of IDs of the channels where the video is published @parameter tags [array(string), optional] : The list of tags assigned to the video
Edit a contribution of type document
PUT /share/v1/document/{id_asset} @get id_asset [integer, required] : The ID of the asset @parameter url [string, required] : The URL of the document @parameter title [string, required] : The title of the document @parameter description [string, required] : The description of the document @parameter original_filename [string, optional] : The original filename of the document @parameter thumbnail_url [string, optional] : The URL of the thumbnail @parameter channels [array(integer), optional] : The list of IDs of the channels where the document is published @parameter tags [array(string), optional] : The list of tags assigned to the document
Create a new contribution of generic type
POST /share/v1/generic @parameter url [string, required] : The URL of the asset @parameter title [string, required] : The title of the asset @parameter content_type [integer, optional] : The content type of the asset. Accepted values : 6, 10, 11, 12, 13 @parameter description [string, required] : The description of the asset @parameter original_filename [string, required] : The original filename of the asset @parameter thumbnail_url [string, optional] : The URL of the thumbnail @parameter channels [array(integer), optional] : The list of IDs of the channels where the asset is published @parameter tags [array(string), optional] : The list of tags assigned to the asset