Sharing
In Limecraft Flow, users usually collaborate within a single production. All team members of the production can access all the material within the production. However, with the Sharing feature, it is possible to share a single clip, selection of clips or a collection of material (as opposed to all the material in the production) with users that are not part of your production.
Create and access a share
Share a collection
POST /production/{prId}/eo/{id}/shareShare an editorial object with one or more users, by default the user has 'VIEW' permissions.
Details
Description
It is possible to add extra permissions. Extra permissions: 'ANNOTATE', 'DOWNLOAD', 'UPLOAD'.
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the editorial object. |
✔ |
Long |
Body Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
Shared object to create. |
✘ |
SharedObjectRequest |
SharedObjectRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
callbackURL |
✘ |
String |
||
clientProperties |
✘ |
Object |
||
description |
✘ |
String |
||
expires |
✘ |
Long |
int64 |
|
label |
✘ |
String |
||
password |
✘ |
String |
||
permissions |
✘ |
List of string |
||
users |
✘ |
List of string |
Return Type
String
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or editorial object was not found. |
|
Body example
{
"permissions": [
"REVIEW",
"DOWNLOAD",
"UPLOAD",
"DOWNLOAD_PROXY",
"REVIEW_STATUS_EDIT"
],
"expires": 4102444800000,
"label": "My Super Label",
"description": "My super description",
"clientProperties": {
"overviewVisible": true,
"identifyUser": false,
"this": "can",
"be": [
"anything"
],
"and": {
"this": {
"means": "anything"
}
}
}
}See also EditorialObjectShare.
To update the share afterwards, you can perform a PUT call to the share:
PUT /production/{prId}/share/{id}_This API call update the shared object. _
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✔ |
Long |
|
|
✔ |
Long |
Body Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✘ |
ShareObject |
ShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Return Type
ShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
409 |
The version in the update object does not match with the version stored causing an optimistic lock. |
|
Share one or more clips
To share a selection of clips, it is first necessary to create an EditorialObject with funnel SelectionShare. This page explains how to create an EditorialObject. The body of the call will contain something like this:
{
"funnel": "SelectionShare",
"title": "some clips"
}After creating the EditorialObject, assign the clips to it as explained here.
Once the clips are attached, share the EditorialObject just like you would share a collection, as explained in the previous section.
Access a share
| We are changing our viewpoint in this section. Now we are not the user creating the share, but the user accessing the share. The latter usually isn’t part of the Production the Share was created in! |
When creating a share, Limecraft Flow will generate a token which regulates access to certain items included in the share and the share itself. This token first needs to be upgraded via a login call. The upgraded token must then be used for subsequent calls to access things in the share.
Login: upgrade the share token
The url being shared will contain the productionId and the Share’s token, for example this (non-functional) link: https://platform.limecraft.com/#shared/production/1234/eyJhIjSomethingSwidiI6MX0.
The first call that needs to happen is a login call on the share. If the share is not password-protected, you can simply POST an empty object {} to it. The Share’s token should be placed in the authorization header Authorization: Bearer <token>. An alternative is to use it as the access_token query parameter: ?access_token=<token>.
The call will respond with an object containing a session token which should be used in subsequent steps (again, in the Authorization header or via the access_token query parameter). The session token grants you access to the share and will expire after one hour of inactivity.
| If the share expires, any sessions created before the expiration will still be active and will allow access to the share. However, the creation of new sessions will be disabled. |
POST /production/{prId}/share/{id}/loginVerify the password and generate new token.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the share. |
✔ |
Long |
Body Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✘ |
Object |
body
Field Name |
Required |
Type |
Description |
Format |
Return Type
SharedUser
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
✔ |
String |
|||
emailHash |
✘ |
String |
||
firstName |
✘ |
String |
||
fullName |
✘ |
String |
||
id |
✔ |
Long |
The id of this resource |
int64 |
lastName |
✘ |
String |
||
lastSeen |
✘ |
Date |
date-time |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
productionId |
✘ |
Long |
int64 |
|
username |
✔ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
404 |
The production or share object was not found. |
|
Get the share data
The next call will fetch the EditorialObjectShare object. Note that the token returned by the login call of the previous call should be placed in the authorization header Authorization: Bearer <token>! An alternative is to use it as the access_token query parameter: ?access_token=<token>.
GET /production/{prId}/share/current__
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✔ |
Long |
Return Type
ShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
0 |
default response |
|
Get the collection and clips
The previous call gave us the EditorialObjectShare object. It contains the id of the EditorialObject it is sharing in its editorialObjectId property. We are now ready to fetch the collection (EditorialObject)!
GET /production/{prId}/eo/{id}Query for accessing a collection with the shared token.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the shared token. |
✔ |
Long |
Return Type
EditorialObject
The EditorialObject this request is for.
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
abstract |
✘ |
String |
||
alternativeTitle |
✘ |
String |
Can contain a second title (with the title field being the primary title) |
|
category |
✘ |
String |
||
categoryId |
✘ |
Long |
The id of the category we belong to |
int64 |
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
customFields |
✘ |
CustomFields |
||
description |
✘ |
String |
Plain text description |
|
extent |
✘ |
String |
||
funnel |
✘ |
String |
Field which can be interpreted as a subtype (besides objectType). Only the objectType determines the structure of the EditorialObject, the funnel does not. It is meant for applications to indicate the EditorialObject is to be interpreted in a specific way. |
|
id |
✔ |
Long |
The id of this resource |
int64 |
includeCategoryName |
✘ |
Boolean |
||
includeChildren |
✘ |
Boolean |
||
includeEdl |
✘ |
Boolean |
||
includeParent |
✘ |
Boolean |
||
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
parent |
✘ |
EditorialObject |
||
parentId |
✘ |
Long |
The id of the parent EditorialObject |
int64 |
productionId |
✘ |
Long |
int64 |
|
status |
✘ |
String |
Status of the EditorialObject. Application-specific implementation. |
|
subObjects_index |
✘ |
Integer |
Order of this EditorialObject inside its parent. Gaps are allowed. |
int32 |
systemFields |
✘ |
CustomFields |
||
title |
✘ |
String |
Contains the primary title of the EditorialObject. |
|
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs PRODUCTION_VIEW rights. |
|
404 |
The production or editorial object was not found. |
|
You can use the following include query parameters to also retrieve the annotations in the same call: includeEntries=true&includeEdl=true&includeAnnotations=true.
Accessing the MediaObject, MediaObjectInstance, MaterialInstance etc. uses the regular calls (authorized via the share token).
Create and access a password-protected share
A share can be protected with a password. Let’s take a look at how to create a password-protected share, and then how to access it as a user not belonging to the production.
Add a password to a share
The user doing the calls in this section is part of the production and able to manage shares ("LIBRARY_SHARE" permission).
|
Creating the share happens in the same way as we did in the previous section. To add a password to it, first update the existing share object by using the following PUT call and setting its passwordProtected to true:
PUT /production/{prId}/share/{id}_This API call update the shared object. _
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✔ |
Long |
|
|
✔ |
Long |
Body Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✘ |
ShareObject |
ShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Return Type
ShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
409 |
The version in the update object does not match with the version stored causing an optimistic lock. |
|
Next, PUT the new password on the share:
PUT /production/{prId}/share/{id}/password_This API call updates the password of a shared object. _
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the share. |
✔ |
Long |
Body Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
Raw version of the password. |
✔ |
String |
body
Field Name |
Required |
Type |
Description |
Format |
Return Type
ShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
409 |
The version in the update object does not match with the version stored causing an optimistic lock. |
|
To change a password, the same sequence can be used. To clear the password, set passwordProtected to false in the first call and save the empty string "" as the password in the second call.
Access a password-protected share
| We are changing our viewpoint in this section: we are now a user accessing the share (usually not part of the production). |
Accessing a password-protected share is similar to what we explained above about accessing a share. The only difference is that we won’t send an empty object to the login call, but our password:
{ "password": "myPassword" }The rest of the sequence is identical.
Create and access a share with identification
A share can be accessed with the share token, but some calls, (e.g., creating a ReviewComment) will require the user to be identified. For other calls, identifying the user first is recommended, so actions can be traced back to a SharedUser.
Create a share which requires identification
| We are changing our viewpoint in this section: we are now a user creating the share (and thus part of the production). |
Some calls (e.g., creating a ReviewComment) will require the user to be identified. the Limecraft Flow Core will always block these calls when the call is not authorized with an identified token. However, the share itself can still be accessed.
In some cases, it is useful to have the user identify as soon as they access the share. E.g. to have a record of "this person viewed the share". This can be enforced by setting clientProperties.identifyUser to true when creating the share. This will result in the Limecraft Flow UI application to require identification before accessing the share.
Note that Limecraft Flow UI is smart enough to automatically ask the user to identify when they try to create a (e.g., creating a ReviewComment), even if clientProperties.identifyUser is not true.
Access a share which requires identification
| We are changing our viewpoint in this section: we are now a user accessing the share (usually not part of the production). |
Identifying is done using the identify call. A successful identify response will be a JSON object which contains
both a token and a sharedUser property. The token is to be used to
authorize any calls from now on. The sharedUser which is returned is either
newly created, or an existing one. See the section on shared users below.
| Identifying does not add any extra security, as anyone can identify as any user! It is meant as a low-friction way of getting some information on who is accessing the share, but it shouldn’t be relied upon for security purposes. |
The identification call can be called in any of these ways:
-
with a
usernameandemail. -
with an empty body. The call will succeed if the provided token already is identified. For instance when sending the share link via email (through Limecraft Flow), Limecraft Flow will automatically use identified tokens in the email. It will return 401 otherwise and therefore needs further identification.
-
with a regular Limecraft Flow access Token
flowAccessTokenin the body of the request. This means as much as ‘I want to access this share context, but be identified as this Limecraft Flow user’. The response will contain a newly created Shared User, and a newly generated token. A Shared User is created even for existing Limecraft Flow users, because needs to work for mentions, and not be shown as anonymous for other share users. -
Another alternative is to put the
sharedUserIdin the body of the request. Limecraft Flow will add the shared user to the share, if it isn’t already.
In practice, the Limecraft Flow UI will use all these mechanisms in an attempt to not bother the user unnecessarily with a screen asking for the username and email:
-
first try the empty body
-
failing that it will try to set
sharedUserIdif the same user previously visited a share -
failing that it will try to set
flowAccessTokenif one is known -
failing that, the user is not identified. If identification is necessary, a screen will be shown asking for username and email.
When using an identified shared token, all objects created in the context of the share will be linked to the shared user via the createdBySharedUserId property.
POST /production/{prId}/share/current/identify__
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✔ |
Long |
Body Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✘ |
IdentifyRequest |
IdentifyRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
✘ |
String |
|||
flowAccessToken |
✘ |
String |
||
sharedUserId |
✘ |
Long |
int64 |
|
username |
✘ |
String |
Return Type
TokenizedSharedUser
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
sharedUser |
✘ |
SharedUser |
||
token |
✘ |
String |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
0 |
default response |
|
| After identifying yourself, you can access the shared collection as explained before. |
Access annotations in the share
Annotations that are explicitly shared or created in the share can be queried, meaning all annotation with attachedEditorialObjectId set to the collection being shared or createdByShareId equal to the share id.
The regular annotation search queries are supported.
GET /production/{prId}/share/{id}/anList all shared annotations within the production.
Details
Description
Returns the search result. This call makes use of Solr query parameters. For more info on those, checkout Solr Query parameters .
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the share. |
✔ |
Long |
Query Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
Compressed result or not. |
✘ |
Boolean |
Return Type
AnnotationSolrDocumentList
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
elapsedTime |
✘ |
Long |
int64 |
|
facetDates |
✘ |
List of FacetField |
||
facetFields |
✘ |
List of IFacetField |
||
facetPivot |
✘ |
Map of object |
||
facetQuery |
✘ |
Map of integer |
int32 |
|
facetRanges |
✘ |
List of object |
||
fieldStatsInfo |
✘ |
Map of IFieldStatsInfo |
||
groupResponse |
✘ |
GroupResponse |
||
highlighting |
✘ |
Map of map |
||
items |
✘ |
List of Component |
||
mediaObjectProperties |
✘ |
Map of map |
||
numFound |
✘ |
Long |
int64 |
|
responseHeader |
✘ |
Map of object |
||
results |
✘ |
List of SolrDocument |
||
start |
✘ |
Long |
int64 |
|
termsResponse |
✘ |
TermsResponse |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs PRODUCTION_VIEW rights. |
|
404 |
The production was not found. |
|
As for all listing calls, paging is supported.
If you only want to search the annotations that are shared (so not the ReviewComments created in the share), you can add a filter on attachedEditorialObjectId, or alternatively in the previous url replace /an with /attachedannotations.
If you only want to search the annotations that are created in the share (in practice: the ReviewComments created through a share), you can add a filter on createdByShareId, or alternatively in the previous url replace /an with /createdannotations.
Edit a share
To change properties of a Share, you use a PUT call to the share:
PUT /production/{prId}/share/{id}_This API call update the shared object. _
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✔ |
Long |
|
|
✔ |
Long |
Body Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
✘ |
ShareObject |
ShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Return Type
ShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
409 |
The version in the update object does not match with the version stored causing an optimistic lock. |
|
See also EditorialObjectShare.
It is not possible to change the password this way. See this section on how to change / set / clear the password.
Share user management
We already mentioned in the section about shares with identification that a SharedUser is created behind the scenes. There are some calls which allow you to explicitly manage these shared users.
List shared users in a share
GET /production/{prId}/share/{id}/shareduserRequest the SharedUsers corresponding to the share object.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the share. |
✔ |
Long |
Return Type
String
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
| As for all listing calls, paging is supported. |
Shared users can be queried by means of filter query parameters (e.g. ?fq=email:Pepromene@limecraft.com) of which the following are currently supported:
| Query parameter | Description |
|---|---|
|
filter shareduser by share’s id |
|
filter shareduser by id |
|
filter shareduser by lastSeen |
|
filter shareduser by username |
|
filter shareduser by email |
|
filter shareduser by firstName |
|
filter shareduser by lastName |
The Limecraft Flow UI share dialog uses this call to render the shared users with who the collection is shared:
Add shared user to a share
A shared user can be created and added to a share using this call:
POST /production/{prId}/share/{id}/shareduserAdd an exiting or create a new SharedUser with the given email address.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the share. |
✔ |
Long |
Body Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✘ |
List of SharedUser |
SharedUser
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
✔ |
String |
|||
emailHash |
✘ |
String |
||
firstName |
✘ |
String |
||
fullName |
✘ |
String |
||
id |
✔ |
Long |
The id of this resource |
int64 |
lastName |
✘ |
String |
||
lastSeen |
✘ |
Date |
date-time |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
productionId |
✘ |
Long |
int64 |
|
username |
✔ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Return Type
SharedUser
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
✔ |
String |
|||
emailHash |
✘ |
String |
||
firstName |
✘ |
String |
||
fullName |
✘ |
String |
||
id |
✔ |
Long |
The id of this resource |
int64 |
lastName |
✘ |
String |
||
lastSeen |
✘ |
Date |
date-time |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
productionId |
✘ |
Long |
int64 |
|
username |
✔ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
Body example
{
"email": "Pepromene@limecraft.com",
"username": "pepromene",
"firstName": "πεπερατοσθαι",
"lastName": "πεπρῶσθαι"
}To actually send the user an email with the share link, use the notify call (see next section).
It’s also possible to add an existing shared user to the share using this call:
PUT /production/{prId}/share/{id}/shareduser/{sharedUserId}Add a SharedUsers to the share object.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the share. |
✔ |
Long |
|
ID of the shared user Id. |
✔ |
Long |
Return Type
SharedUser
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
✔ |
String |
|||
emailHash |
✘ |
String |
||
firstName |
✘ |
String |
||
fullName |
✘ |
String |
||
id |
✔ |
Long |
The id of this resource |
int64 |
lastName |
✘ |
String |
||
lastSeen |
✘ |
Date |
date-time |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
productionId |
✘ |
Long |
int64 |
|
username |
✔ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
Notify shared user in a share by email
In the previous section, we learned how to add a shared user to a share. Usually, this is followed by a call to inform the user via email about the link of the share. This is done with the notify call:
POST /production/{prId}/share/{id}/shareduser/{sharedUserId}/notifyNotify a SharedUser.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the share. |
✔ |
Long |
|
ID of the shared user. |
✔ |
Long |
Body Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
Body of the notify request. |
✘ |
NotifyRequest |
NotifyRequest
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
callbackURL |
✘ |
String |
Return Type
SharedUser
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
✔ |
String |
|||
emailHash |
✘ |
String |
||
firstName |
✘ |
String |
||
fullName |
✘ |
String |
||
id |
✔ |
Long |
The id of this resource |
int64 |
lastName |
✘ |
String |
||
lastSeen |
✘ |
Date |
date-time |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
productionId |
✘ |
Long |
int64 |
|
username |
✔ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
The body of the call contains a callbackURL parameter with some support for templating:
{
"callbackURL": "https://labs.limecraft.com/#shared/production/[(${production.id})]/[(${token})]"
}The template part is marked by [(${ some_expression })]. Currently, the following objects can be used in the template expression:
-
token— the access token for the share -
production— the production of the share -
share— the share itself -
creator— the creator of the share
Remove shared user from a share
To remove an individual shared user, use this call:
DELETE /production/{prId}/share/{id}/shareduser/{sharedUserId}The call for removing shared user.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the share. |
✔ |
Long |
|
ID of the shared user. |
✔ |
Long |
Return Type
SharedUser
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
✔ |
String |
|||
emailHash |
✘ |
String |
||
firstName |
✘ |
String |
||
fullName |
✘ |
String |
||
id |
✔ |
Long |
The id of this resource |
int64 |
lastName |
✘ |
String |
||
lastSeen |
✘ |
Date |
date-time |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
productionId |
✘ |
Long |
int64 |
|
username |
✔ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
It’s also possible to remove shared users in bulk by using a query (e.g. ?fq=email:Pepromene@limecraft.com):
DELETE /production/{prId}/share/{id}/shareduserThe call for removing shared user with a query call.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the share. |
✔ |
Long |
Return Type
ShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs LIBRARY_SHARE rights. |
|
404 |
The production or share object was not found. |
|
the following query filters are currently supported:
| Query parameter | Description |
|---|---|
|
filter shareduser by share’s id |
|
filter shareduser by id |
|
filter shareduser by lastSeen |
|
filter shareduser by username |
|
filter shareduser by email |
|
filter shareduser by firstName |
|
filter shareduser by lastName |
List shares in a production
If you want an overview of what is shared in your production, you can use this call:
GET /production/{prId}/shareThe call for listing shareObjects for production, editorial object, mediaobject or annotation.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
Query Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
Editorial object id. |
✔ |
Long |
Return Type
String
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs PRODUCTION_VIEW rights. |
|
404 |
The production was not found. |
|
Shares can be queried by means of filter query parameters of which the following are currently supported:
| Query parameter | Description |
|---|---|
|
filter by mediaObject id |
|
filter by editorialObject id |
|
filter by sharedWith id |
|
filter by annotation id |
|
filter by type |
|
filter by expiery date |
|
filter by label |
|
filter by description |
|
filter by clientProperties using dotted notation |
|
filter based on the value of deleted (true or false) |
|
filter by deleted timestamp |
To list the shares in a collection, use a filter query fq parameter on the editorialObjectId field, or use this dedicated call:
GET /production/{prId}/eo/{id}/shareList shares of an editorial object.
Details
Description
Parameters
Path Parameters
| Name | Description | Required | Type |
|---|---|---|---|
|
ID of the production. |
✔ |
Long |
|
ID of the editorial object. |
✔ |
Long |
Return Type
EditorialObjectShareObject
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
clientProperties |
✘ |
Object |
||
created |
✘ |
Date |
The time when this resource was created |
date-time |
createdBy |
✘ |
String |
The request or process that created this resource |
|
creatorId |
✘ |
Long |
The id of the user who created this resource |
int64 |
deleted |
✘ |
Boolean |
||
deletedTimestamp |
✘ |
Date |
date-time |
|
description |
✘ |
String |
Description of the share. It can contain a description of what the share contains, or what is expected of the user accessing it. |
|
editorialObjectId |
✘ |
Long |
int64 |
|
expires |
✘ |
Date |
The share token will no longer work after this date |
date-time |
id |
✔ |
Long |
The id of this resource |
int64 |
label |
✘ |
String |
A label or title of the share. In the UI this is shown as the title when accessing the share. |
|
lastUpdated |
✘ |
Date |
The time when this resource was last updated |
date-time |
modifiedBy |
✔ |
String |
The request or process responsible for the last update of this resource |
|
objectType |
✘ |
String |
The data model type or class name of this resource |
|
passwordProtected |
✘ |
Boolean |
||
permissions |
✘ |
Set of string |
||
productionId |
✘ |
Long |
int64 |
|
sharedWithId |
✘ |
Long |
int64 |
|
token |
✘ |
String |
||
version |
✔ |
Long |
The version of this resource, used for Optimistic Locking |
int64 |
Content Type
-
application/json
Responses
| Code | Description | Datatype |
|---|---|---|
200 |
The request was successful. |
|
403 |
The user needs PRODUCTION_VIEW rights. |
|
404 |
The production or editorial object was not found. |
|