Delivery Request Templating

A Delivery Workspaces contains many different Delivery Requests, one for each type of material or information that needs to be delivered. Typically, these requests are not created directly. Rather, a "template" is set up, indicating which Delivery Requests should be created for each series, episode, program, …​ (represented by EditorialObjects) in the Delivery Workspace.

This "template" is stored in a DeliveryRequestTemplateGroup, which is basically a container for two lists:

The links above contain more detailed information about the structure. Here, we’ll just give a short example:

{
    "objectType": "DeliveryRequestTemplateGroup",

    // reference to the DeliveryRequestTemplateGroup
    "handle": "my_template",
    "label": "First template group",

    // possible "kinds" of requests, represented by a list of
    // DeliveryRequestTemplate
    "deliveryRequestTemplates": [
        {
            "handle": "episodePromoVideo",
            "objectType": "DeliveryRequestTemplate",
            "label": "Request For Promo File",
            "group": "Video",
            "subGroup": "Promo",
            "description": "Give me the promo file"
        }
    ],

    // which DeliveryRequests should be created for each EditorialObject?
    "deliveryRequestTemplateInstances": [
        {
            "templateContext": "EditorialObject",

            // if the EditorialObject type custom field equals "Episode"
            "query": {
                "key": "editorialObject.customFields.type",
                "values": ["Episode"]
            },

            // then create or update a DeliveryRequest based on the DeliveryRequestTemplate
            // with this handle
            "templateHandle": "episodePromoVideo",

            // force these options on the DeliveryRequest, even if the DeliveryRequestTemplate
            // contains some other value. Useful for dynamically filling in values based on
            // fields of the EditorialObject
            "overrideProperties": {
                "formFieldValues": {
                    "externalManifestationId": {
                      "@value": "editorialObject.customFields.externalManifestationId.value"
                    }
                }
            }
        }
    ]
}

A DeliveryRequestTemplateGroup is referenced by its handle when bootstrapping a Delivery workspace. It will then also be used to update DeliveryRequests when Editorial Object changes happen.

Reading your DeliveryRequestTemplateGroup(s)

The DeliveryRequestTemplateGroups are defined on the Account level. It is perfectly possible to have multiple DeliveryRequestTemplateGroups on an Account. There could for example be one to describe "a fiction series delivery workspace" and another to describe a "film delivery workspace". In practice though, it is often sufficient to have a single one.

To list the DeliveryRequestTemplateGroups, use the following API call

GET /account/{accountId}/delivery_request_template_group

This call retrieves all delivery request template groups for an account.

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long
Return Type

DeliveryRequestTemplateGroup

Field Name Required Type Description Format

account

✘

Account

activeStatus

✘

String

Enum: Active, Archived,

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

deliveryRequestTemplateInstances

✘

Set of DeliveryRequestTemplateInstance

deliveryRequestTemplates

✘

Set of DeliveryRequestTemplate

handle

✘

String

id

✔

Long

The id of this resource

int64

label

✘

String

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

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Content Type

  • application/json

Responses
Table 1. http response codes
Code Description Datatype

200

The request was successful.

DeliveryRequestTemplateGroup

403

The user needs ACCOUNT_MANAGE rights.

ForbiddenError

404

The account was not found.

NotFoundError

If you know the id of the DeliveryRequestTemplateGroup you are interested in, use this call to get more details

GET /account/{accountId}/delivery_request_template_group/{id}

This call retrieves a delivery request template group for an account, based on their ids.

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long

id

ID of the group.

✔

Long
Return Type

DeliveryRequestTemplateGroup

Field Name Required Type Description Format

account

✘

Account

activeStatus

✘

String

Enum: Active, Archived,

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

deliveryRequestTemplateInstances

✘

Set of DeliveryRequestTemplateInstance

deliveryRequestTemplates

✘

Set of DeliveryRequestTemplate

handle

✘

String

id

✔

Long

The id of this resource

int64

label

✘

String

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

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Content Type

  • application/json

Responses
Table 2. http response codes
Code Description Datatype

200

The request was successful.

DeliveryRequestTemplateGroup

403

The user needs ACCOUNT_MANAGE rights.

ForbiddenError

404

The account was not found.

NotFoundError

You can use the include=deliveryRequestTemplateInstances&include=deliveryRequestTemplates query parameters to receive the "full template" including its DeliveryRequestTemplates and DeliveryRequestTemplateInstances, which will give a result similar to the example at the top of this page.

Updating the DeliveryRequestTemplateGroup

You can update your DeliveryRequestTemplateGroup using the following call. The body of the call should be the entire DeliveryRequestTemplateGroup, including all the deliveryRequestTemplateInstances and deliveryRequestTemplates.

PUT /account/{accountId}/delivery_request_template_group/{id}

This call updates a delivery request template group for an account.

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long

id

ID of the group.

✔

Long
Body Parameters
Name Description Required Type

DeliveryRequestTemplateGroup

✘

DeliveryRequestTemplateGroup

DeliveryRequestTemplateGroup

Field Name Required Type Description Format

account

✘

Account

activeStatus

✘

String

Enum: Active, Archived,

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

deliveryRequestTemplateInstances

✘

Set of DeliveryRequestTemplateInstance

deliveryRequestTemplates

✘

Set of DeliveryRequestTemplate

handle

✘

String

id

✔

Long

The id of this resource

int64

label

✘

String

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

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Return Type

DeliveryRequestTemplateGroup

Field Name Required Type Description Format

account

✘

Account

activeStatus

✘

String

Enum: Active, Archived,

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

deliveryRequestTemplateInstances

✘

Set of DeliveryRequestTemplateInstance

deliveryRequestTemplates

✘

Set of DeliveryRequestTemplate

handle

✘

String

id

✔

Long

The id of this resource

int64

label

✘

String

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

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Content Type

  • application/json

Responses
Table 3. http response codes
Code Description Datatype

200

The request was successful.

DeliveryRequestTemplateGroup

403

The user needs ACCOUNT_MANAGE rights.

ForbiddenError

404

The account was not found.

NotFoundError

This call will update a single DeliveryRequestTemplateGroup, synchronizing all deliveryRequestTemplates and deliveryRequestTemplateInstances.

The deliveryRequestTemplates are matched based on their handle. DeliveryRequestTemplates which do not exist yet are created; existing DeliveryRequestTemplates are updated; existing DeliveryRequestTemplates which are no longer in the update object are deleted.

The deliveryRequestTemplateInstances are created anew and the old ones are discarded.

The resulting DeliveryRequestTemplateGroup is a template group that matches the input update object.

A more fine-grained update of the DeliveryRequestTemplateGroup is also possible, by using the PATCH call below. When using this call, it is important to also add the include=deliveryRequestTemplateInstances&include=deliveryRequestTemplates query parameters, otherwise the PATCH call will fail. As always, the PATCH call follows the JSON Patch mechanism.

PATCH /account/{accountId}/delivery_request_template_group/{id}

This call patches a delivery request submission template group of a production based on their ids.

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long

id

ID of the group.

✔

Long
Body Parameters
Name Description Required Type

body

✘

Object

body

Field Name

Required

Type

Description

Format
Query Parameters
Name Description Required Type

version

✘

Long
Return Type

DeliveryRequest

Field Name Required Type Description Format

activeStatus

✘

String

Is the request active, or is it archived?

Enum: Active, Archived,

allowFlowTransfer

✘

Boolean

Is the request allowed to transfer material to Limecraft Flow, or should it transfer to a linked VolumeAccess?

allowMultipleSubmissions

✘

Boolean

Make it possible for multiple submissions to be “active” (not in an end-state APPROVED or REJECTED) at the same time.

assignee

✘

DeliveryRequestAssignee

clientProperties

✔

Object

continueFromPreviousSubmission

✘

Boolean

This property influences if a new DeliveryRequestSubmission in the request dialog starts empty (if false) or starts from a clone of the last submission (if true). It is not interpreted by the API, but should be implemented by the client UI.

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

deliveryDate

✘

Date

When should this request be delivered?

date-time

deliveryRequestType

✔

String

This should be a unique identifier of this type of request. When integrating with Limecraft Flow DeliveryRequests, you can use this property to check the type of request you are dealing with (rather than for instance use the group and subGroup fields). We strongly advise to only use alphanumerical characters and dashes to create a deliveryRequestType handle. Special characters, accents etc. should be avoided.

description

✔

String

A plain-text description of what is expected to be provided in the request. It can be shown to the user as information.

editorialObject

✘

EditorialObject

editorialObjectId

✘

Long

int64

expectedDeliveryDate

✘

Date

When do we expect this request be delivered?

date-time

formFieldValues

✘

Object

formFieldsDefinition

✘

FormFieldsDefinition

group

✔

String

Used to organize DeliveryRequests, but the value itself is not interpreted by the system.

hideDeliveryDate

✘

Boolean

Is a client user interface not allowed to show the delivery date?

id

✔

Long

The id of this resource

int64

label

✔

String

A human readable label for the DeliveryRequest. This can be shown to the user.

lastSubmissionApprovedDate

✘

Date

Date of approval of the last submission

date-time

lastUpdated

✘

Date

The time when this resource was last updated

date-time

layout

✔

Object

metadataOnly

✘

Boolean

When true, the request will not ask for file uploads. It will only show a metadata form.

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

reviewer

✘

DeliveryRequestReviewer

showPreviousSubmissions

✘

Boolean

Influences if the version sidebar in the request dialog is shown or not.

subGroup

✔

String

Used to organize DeliveryRequests, but the value itself is not interpreted by the system.

submissionStatus

✘

String

The status the DeliveryRequests last DeliveryRequestSubmission is in.

Enum: Open, Draft, AwaitingProbe, AwaitingAutoValidation, AwaitingDelivery, AwaitingReview, Accepted, Rejected, DraftFailed, DeliveryFailed,

submissions

✘

Set of DeliveryRequestSubmission

submitLocked

✘

Boolean

Marks the request as being "submission locked". This will not allow submit on existing DeliveryRequestSubmissions and will not allow creating new DeliveryRequestSubmissions

tag

✘

Set of string

templateId

✘

String

validationRules

✔

ValidationRules

version

✔

Long

The version of this resource, used for Optimistic Locking

int64

volumeAccesses

✘

Set of VolumeAccess

When not uploading to Flow, the transfer will upload to one of the VolumeAccesses in here.
Content Type

  • application/json

Responses
Table 4. http response codes
Code Description Datatype

200

The request was successful.

DeliveryRequest

403

The user needs ACCOUNT_MANAGE rights.

ForbiddenError

404

The account or delivery request was not found.

NotFoundError

409

The version in the update object does not match with the version stored causing an optimistic lock.

ConflictError