Workflows

Workflows represent one of the core signature features of the Limecraft Flow platform. Working with our API in use cases that involve processing of audiovisual media in any way, you will most likely encounter them.

In most cases, starting a heavy processing task (ingesting, transcoding, automatic transcription, subtitling, etc.) initiates a workflow which can last for some time, depending on the various factors like its intensity, available resources, amount of traffic…​ When the workflow starts, our API will return a workflow report, which will indicate the current status of the workflow — started, in progress or failed. Workflows and their tasks run asynchronously in the background and the workflow report is updated as the workflow progresses.

Wait for the workflow to finish

The WorkflowReport describes the status of a workflow. It is available as soon as the workflow is started. Its status field will go through a couple of values but will end up in Completed if the workflow succesfully completed, or in Error if an error occured while executing the workflow (or in Cancelled if the workflow was cancelled).

To wait for the WorkflowReportstatus to change, there are a couple of options.

Use progress call

This call uses server-sent-events to keep a client updated on the state of the workflow.

GET /production/{prId}/{alias}/{id}/progress

This is a generic workflow progress monitor call, which can be used to monitor the ingest workflow in particular, but all other workflows as well.

Details
Description

Wait for the given workflow to finish.

Parameters
Path Parameters
Name Description Required Type

alias

Either workflow or workflowReport. Both are aliases of each other.

✔

String

prId

ID of the production.

✔

Long

id

ID of the workflow.

✔

String
Return Type

String

Content Type

  • application/json

Responses
Table 1. http response codes
Code Description Datatype

200

The request was successful.

String

403

The user needs PRODUCTION_VIEW rights.

ForbiddenError

404

The production or workflow was not found.

NotFoundError

The endpoint emits an init event, progress events and a result event. The data of the event contains the WorkflowReport.

Use Polling

An alternative is to request the WorkflowReport regularly and check its status.

GET /production/{prId}/workflowreport/{workflowId}

__

Details
Description
Parameters
Path Parameters
Name Description Required Type

prId

✔

Long

workflowId

✔

String
Return Type

WorkflowReport

Field Name Required Type Description Format

adminOnly

✘

Boolean

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

createdByShareId

✘

Long

int64

createdBySharedUserId

✘

Long

int64

creatorId

✘

Long

The id of the user who created this resource

int64

errorReports

✘

List of TaskReport

funnel

✘

String

id

✔

Long

The id of this resource

int64

label

✘

String

User-friendly label of the workflow

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

publishedFiles

✘

List of object

Files generated by the workflow, which can be downloaded.

removeFromQuota

✘

Boolean

requiredRights

✘

List of ProductionPermission

startupParameters

✘

Object

status

✘

String

Enum: Inited, Started, Completed, Error, Cancelled, Paused, CompletedPending, ErrorPending, WaitForCallback, Scheduled, Skipped,

successFul

✘

Boolean

taskReports

✘

List of TaskReport

variables

✘

Object

version

✔

Long

The version of this resource, used for Optimistic Locking

int64

workflowCompleted

✘

Date

When did the workflow complete?

date-time

workflowFailed

✘

Date

When did the workflow fail?

date-time

workflowId

✘

String

The id of the workflow. This can be used to retrieve the workflow status.

workflowStarted

✘

Date

When was the workflow started?

date-time

workflowTask

✘

String

workflowType

✘

String

Enum: INGEST, SPEECH, IPPAMEXPORT, IPPAMSYNC, MOIEXPORT, REMOTE_SPEECH, VOLDEMORT_SPEECH, TRANSCODE, AUDIOANALYZE, EXPORT_VWFLOW, FEATURE_EXTRACTION, BLACK_FRAME, STON_APPROVE, AAF_EXPORT, FCP_EXPORT, VOLDEMORT_SPEECH_2, KALDI_SPEECH, SUBTITLING, MIGRATE, INDEX, BACKUP, VOLDEMORT_SPEECH_3, VOLDEMORT_SPEECH_4, VOLDEMORT_SPEECH_5, TRANSLATION, INDEX_SWITCH, SIMPLEINGEST, CLONE, UPDATE_CATEGORY, WEBHOOK, SETKEEPER_ATTACH, PDF_EXPORT, SHOT_DETECTION, EXPORT, REMOTE_HELLO_WORLD, CUSTOM, UNKNOWN, CHANGE_AUDIO_LAYOUT, WORKSPACE_BOOTSTRAP, MEDIA_TRANSFER_COMPLETE, MEDIA_TRANSFER_FAILED, DELIVERY_REQUEST_SUBMISSION_CLIP_PROBED, DELIVERY_REQUEST_SUBMISSION, ADVANCED_SUBTITLE, TRANSCRIPTION_SUMMARIZE, VOLUME_TRANSFER_COMPLETE, VOLUME_TRANSFER_FAILED, VOLUME_TRANSFER_MONITOR,
Content Type

  • application/json

Responses
Table 2. http response codes
Code Description Datatype

0

default response

WorkflowReport

When things go wrong

In the previous section we learned how to wait for a workflow to complete. One of the end states was Error. If a workflow goes into status Error, it will usually have more information on what went wrong in the errorReports field of the WorkflowReport.

The message of the entries in this list contains a String with information which can be presented to an end user.

Example errorReports
{
    errorReports: [
        {
            "created": 0,
            "duration": 6013,
            "end": 1702049014287,
            "id": 0,
            "lastHeartBeat": 0,
            "loopIndex": -1,
            "message": "No online material found",
            "objectType": "TaskReport",
            "output": {},
            "priority": 0,
            "progress": 1,
            "start": 1702049008274,
            "status": "FAILURE",
            "taskLabel": "Extract features",
            "taskName": "FEATURE_EXTRACT",
            "taskReferenceName": "serviceTaskShotDetect",
            "type": "AUTO"
        }
    ]
}

Query workflows

List production specific workflows

GET /production/{prId}/workflowreport

This call lists production specific workflow reports.

Details
Description

Combine this call with filter queries and paging to retrieve desired workflow reports. It returns a list of workflow reports.

Parameters
Path Parameters
Name Description Required Type

prId

ID of the production.

✔

Long
Return Type

String

Content Type

  • application/json

Responses
Table 3. http response codes
Code Description Datatype

200

The request was successful.

String

403

The user needs PRODUCTION_VIEW rights.

ForbiddenError

404

The production was not found.

NotFoundError

As for all listing calls, Paging is supported.

List account specific workflows

GET /account/{aId}/{alias}

This call lists account specific workflows. For alias use either workflow or workflowreport.

Details
Description

Combine this call with filter queries and paging to retrieve desired workflow reports. It returns a list of workflows/ workflow reports.

Parameters
Path Parameters
Name Description Required Type

alias

Alias - workflow or workflowreport

✔

String

aId

ID of an account.

✔

Long
Return Type

WorkflowReport

Field Name Required Type Description Format

adminOnly

✘

Boolean

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

createdByShareId

✘

Long

int64

createdBySharedUserId

✘

Long

int64

creatorId

✘

Long

The id of the user who created this resource

int64

errorReports

✘

List of TaskReport

funnel

✘

String

id

✔

Long

The id of this resource

int64

label

✘

String

User-friendly label of the workflow

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

publishedFiles

✘

List of object

Files generated by the workflow, which can be downloaded.

removeFromQuota

✘

Boolean

requiredRights

✘

List of ProductionPermission

startupParameters

✘

Object

status

✘

String

Enum: Inited, Started, Completed, Error, Cancelled, Paused, CompletedPending, ErrorPending, WaitForCallback, Scheduled, Skipped,

successFul

✘

Boolean

taskReports

✘

List of TaskReport

variables

✘

Object

version

✔

Long

The version of this resource, used for Optimistic Locking

int64

workflowCompleted

✘

Date

When did the workflow complete?

date-time

workflowFailed

✘

Date

When did the workflow fail?

date-time

workflowId

✘

String

The id of the workflow. This can be used to retrieve the workflow status.

workflowStarted

✘

Date

When was the workflow started?

date-time

workflowTask

✘

String

workflowType

✘

String

Enum: INGEST, SPEECH, IPPAMEXPORT, IPPAMSYNC, MOIEXPORT, REMOTE_SPEECH, VOLDEMORT_SPEECH, TRANSCODE, AUDIOANALYZE, EXPORT_VWFLOW, FEATURE_EXTRACTION, BLACK_FRAME, STON_APPROVE, AAF_EXPORT, FCP_EXPORT, VOLDEMORT_SPEECH_2, KALDI_SPEECH, SUBTITLING, MIGRATE, INDEX, BACKUP, VOLDEMORT_SPEECH_3, VOLDEMORT_SPEECH_4, VOLDEMORT_SPEECH_5, TRANSLATION, INDEX_SWITCH, SIMPLEINGEST, CLONE, UPDATE_CATEGORY, WEBHOOK, SETKEEPER_ATTACH, PDF_EXPORT, SHOT_DETECTION, EXPORT, REMOTE_HELLO_WORLD, CUSTOM, UNKNOWN, CHANGE_AUDIO_LAYOUT, WORKSPACE_BOOTSTRAP, MEDIA_TRANSFER_COMPLETE, MEDIA_TRANSFER_FAILED, DELIVERY_REQUEST_SUBMISSION_CLIP_PROBED, DELIVERY_REQUEST_SUBMISSION, ADVANCED_SUBTITLE, TRANSCRIPTION_SUMMARIZE, VOLUME_TRANSFER_COMPLETE, VOLUME_TRANSFER_FAILED, VOLUME_TRANSFER_MONITOR,
Content Type

  • application/json

Responses
Table 4. http response codes
Code Description Datatype

200

The request was successful.

WorkflowReport

403

The user needs ACCOUNT_VIEW rights.

ForbiddenError

404

The account was not found.

NotFoundError

Workflows can be queried by means of filter query parameters of which the following are currently supported

Query parameter Description Example

funnel

filter workflows by property funnel

/api/workflowreport?fq=funnel:export

name

filter workflows by property name

/api/workflowreport?fq=name:WorkflowName

workflowStarted

filter workflows by property workflowStarted timestamp

/api/workflowreport?fq=workflowStarted:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]

workflowCompleted

filter workflows by property workflowCompleted timestamp

/api/workflowreport?fq=workflowStarted:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]

workflowFailed

filter workflows by property workflowFailed timestamp

/api/workflowreport?fq=workflowFailed:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]

mediaObject

filter workflows by mediaObjectId

/api/workflowreport?fq=mediaObject:1

editorialObject

filter workflows by editorialObjectId

/api/workflowreport?fq=editorialObject:1

createdByShare

filter workflows by createdByShareId

/api/workflowreport?fq=createdByShare:1

createdBySharedUser

filter workflows by createdBySharedUserId

api/production/123/file?fq=deletedTimestamp:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]

creator

filter workflows by property creator id

/api/workflowreport?fq=creator:1

created

filter workflows by property created timestamp

/api/workflowreport?fq=created:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]

account

filter workflows by accountId

/api/workflowreport?fq=account:1

production

filter workflows by productionId

/api/workflowreport?fq=production:1

workflowType

filter workflows by workflowType

/api/workflowreport?fq=workflowType:UNKNOWN

status

filter workflows by status (Inited, Started, Completed, TestErrorInternal, Cancelled, Paused, CompletedPending, ErrorPending, WaitForCallback)

/api/workflowreport?fq=status:ErrorPending

label

filter workflows by label

/api/workflowreport?fq=label:fingerprint

workflowTask

filter workflows by workflowTask

/api/workflowreport?fq=workflowTask:fingerprint

startupParameters

filter workflows by startupParameters

Call example

The following call will fetch all ingest workflows for a production which has an id set to 3.

/api/workflowreport?fq=workflowType:INGEST&fq=productionId:3

As for all listing calls, paging is supported.

Search through indexed workflows

There is also a search interface available for workflows. The advantage of this interface is that it is usually much faster to respond than the query interface. The disadvantage is that it might lag behind a few seconds. E.g., a workflow might still be running according to the search results, while in reality it might have finished already.

Search indexed workflows of a production

GET /production/{pId}/workflow/search

Search for workflows in the account.

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

pId

ID of a production.

✔

Long
Return Type

WorkflowSolrDocumentList

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
Table 5. http response codes
Code Description Datatype

200

The search request was successful.

WorkflowSolrDocumentList

403

The user needs PRODUCTION_VIEW rights.

ForbiddenError

404

The production was not found.

NotFoundError

Search indexed workflows of an account

GET /account/{aId}/workflow/search

Search for workflows in the account.

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

aId

ID of an account.

✔

Long
Return Type

WorkflowSolrDocumentList

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
Table 6. http response codes
Code Description Datatype

200

The search request was successful.

WorkflowSolrDocumentList

403

The user needs ACCOUNT_VIEW rights.

ForbiddenError

404

The production was not found.

NotFoundError