EVENTS¶

Events are central to the ControlHub and are at the heart of managing both streaming and on-demand content.

Event Object¶

{
    "video": null,
    "id": "346eb986-1248-4391-9ebc-c1f35bb27cd8",
    "channelId": "a32a5a2d-88b5-4fae-8a1f-0fb258129def",
    "channel": "Example Channel",
    "vuflowId": "fcc587e5-0dfd-4ade-b935-d6b0904f358f",
    "vuflow": "Example Vuflow",
    "remixflowId": null,
    "remixflow": "",
    "archiverflowId": null,
    "archiverflow": "",
    "infrastructureProfileId": null,
    "infrastructureProfile": "",
    "state": 11,
    "stateString": "VOD_PUBLIC",
    "mp4State": 0,
    "mp4StateString": "NONE",
    "eventTypeId": "21c2c17b-d129-4957-87c4-97ff81e0b64b",
    "eventType": "Example Event Type",
    "eventTypeColour": null,
    "roomId": null,
    "room": "",
    "channelProfileId": "26a0228e-f1b2-497d-9cb2-246ffc4d3224",
    "customPropertyConfigurationId": null,
    "title": "Example Event",
    "refId": "reference-identifier-01",
    "externalId": "external-identifier-01",
    "contentId": "346eb986-1248-4391-9ebc-c1f35bb27cd8",
    "description": null,
    "autoStart": false,
    "autoEnd": false,
    "autoPublish": false,
    "autoStartPublications": false,
    "autoProvisionInfrastructure": false,
    "autoTerminateInfrastructure": false,
    "embededVodTimestamps": true,
    "capturingLive2Vod": false,
    "externalUpdateAllowed": false,
    "displayStart": "1970-01-01T09:00:00Z",
    "displayEnd": "1970-01-01T09:30:00Z",
    "scheduledStart": "1970-01-01T09:00:00Z",
    "scheduledEnd": "1970-01-01T09:30:00Z",
    "scheduledChannelStart": null,
    "scheduledChannelEnd": null,
    "actualLiveStart": "1970-01-01T08:46:52Z",
    "actualLiveEnd": "1970-01-01T09:49:57Z",
    "publishedStart": "1970-01-01T08:46:52Z",
    "publishedEnd": "1970-01-01T09:49:57Z",
    "instantVodStart": "1970-01-01T09:00:05Z",
    "instantVodEnd": "1970-01-01T09:31:00Z",
    "scheduledProvisionAt": null,
    "scheduledTerminateAt": null,
    "captureVodStart": "1970-01-01T09:00:05Z",
    "captureVodEnd": "1970-01-01T09:31:00Z",
    "dateCreated": "1970-01-015T08:30:36Z",
    "dateModified": "1970-01-01T09:49:36Z",
    "dateDeleted": null,
    "drmJson": "{\"drm_provider\":\"NONE\"}",
    "drmData": null,
    "additionalStreamingOptions": "--archive_segment_length=600 --archiving=1 --archive_length=28800 --dvr_window_length=28800 --restart_on_encoder_reconnect --iss.minimum_fragment_length=8 --hls.minimum_fragment_length=8 --hds.minimum_fragment_length=8 --hls.client_manifest_version=4 --hls.no_audio_only --hls.no_multiplex",
    "dvrLength": 28800,
    "dvrLengthUrlParam": 28800,
    "maxBitrateUrlParam": null,
    "minBitrateUrlParam": null,
    "vodDrm": false,
    "taskEngineJson": "{...}",
    "thumbnail": null,
    "thumbnailUrl": null,
    "documentUrl": "https://vis.example.vualto.com/api/document/event/346eb986-1248-4391-9ebc-c1f35bb27cd8",
    "tagUrl": "https://vis.example.vualto.com/api/tag/event/346eb986-1248-4391-9ebc-c1f35bb27cd8",
    "customProperties": [],
    "categories": [],
    "category": null,
    "categoryId": null,
    "provisionInfo": null,
    "remixDrmJson": null,
    "remixDrmData": null,
    "remixDrm": false,
    "archiverCaptureId": null,
    "archiverProfileId": null,
    "archiverStart": null,
    "archiverEnd": null
}

Notes: See the respective pages for the structure of Categories and CustomProperties. CategoryId will specify the first Category if there are multiple Categories set. Category will contain the first Category Label if there are multiple Categories set.

Video Structure:

An Event object often specifies a Video object, which contains information on the streaming URLs and protocols.

Below is an example indicating a typical structure. Depending on the Event State different URL objects are populated, but the structure within each is similar.

Other infrastructure information is also included, such as rampServers, and this is defined by the selected Channel and it’s configuration.

{
  "video": {
        "webPageUrl": "url-here",
        "playerUrl": "url-here",
        "embedCode": "iframe-here",
        "scriptablePlayerUrl": "url-here",
        "scriptableEmbedCode": "embed-code-here",
        "requestedStreamTime": {
            "inPointOriginalString": null,
            "outPointOriginalString": null,
            "inPointDateTime": null,
            "outPointDateTime": null,
            "inPointTimeSpan": "00:00:00",
            "outPointTimeSpan": "00:00:00",
            "inPointHasValue": false,
            "outPointHasValue": false,
            "inPointIsAbsoluteDateTime": false,
            "outPointIsAbsoluteDateTime": false
        },
        "requestedAudioOnly": false,
        "requestedAutoStart": false,
        "liveUrls": [
            {
                "streamProtocol": 0,
                "streamProtocolString": "HLS",
                "url": "url-here",
                "absoluteUrlWithPathNoQuery": "url-here",
                "streamSource": 0,
                "streamSourceString": "CDN_PRIMARY_INDEX_0"
            }
        ],
        "livePlayoutProfileUrls": {},
        "vodUrls": [],
        "currentStateUrls": [
            {
                "streamProtocol": 0,
                "streamProtocolString": "HLS",
                "url": "url-here",
                "absoluteUrlWithPathNoQuery": "url-here",
                "streamSource": 0,
                "streamSourceString": "CDN_PRIMARY_INDEX_0"
            }
        ],
        "archiverCapturePublishingPointUrls": [],
        "privateMp4Url": "http://private-url-here.com/path-to-content.mp4",
        "publicMp4Url": "https://public-url-here.com/path-to-content.mp4",
        "websiteplayerUrl": "https://player-url-here.com/path-to-page",
        "websiteEmbedCode": "",
        "scriptableWebsitePlayerUrl": "https://player-url-here.com/path-to-page-with-scripts",
        "scriptableWebsiteEmbedCode": "",
        "publishingPointUrls": [
            {
                "url": "url-here",
                "state": "state-here",
                "hasStarted": false,
                "lastUpdated": "iso8601-datetime-here",
                "receivingData": false
            }
        ],
        "rampServers": [
            {
                "serverAddress": "address-here",
                "apiKey": "api-key-here",
                "location": "location-here",
                "proxyPass": "url-here",
                "playerAddress": "address-here",
                "proxyPassEmpty": "url-here"
            },
        ],
        "remixUrls": [],
        "archiverUrls": []
    }
}

Note: when requesting many Event objects, the video object is not generated to improve performance.

Event Collection¶

Certain endpoints will return an Event collection, which includes pagination information. Shown below, the results propery contains an array of Event objects.

{
  "pageSize": 10,
  "totalCount": 3,
  "results": [
    {},
    {},
    {}
  ]
}

Supported Actions¶

POST `/event/`¶

Add or Update an Event.

Request Body:

Below are the parameter values that can be provided when adding/updating an Event.

It is recommended to submit this as JSON though, as elements such as tags are an array of objects.

  Id: {Guid} 

  Title: {string}

  RefId: {string}

  ExternalId: {string}

  ScheduledStart: {ISO8601 string}

  ScheduledEnd: {ISO8601 string}

  PublishedStart: {ISO8601 string}

  PublishedEnd: {ISO8601 string}

  RoomId: {Guid}

  EventTypeId: {Guid}

  CategoryId: {Guid}

  ChannelId: {Guid}
  
  AutoStart: {bool}

  AutoEnd: {bool}

  AutoProvisionInfrastructure: {bool}

  AutoTerminateInfrastructure: {bool}

  AutoPublish: {bool}

  AutoStartPublications: {bool}

  Tags: {array of TagModel} - see below for the structure.

  DrmJson": {escaped JSON string}

  AdditionalStreamingOptions": {string}

  EventState: {EventState}

  TaskEngineJson: {string}

  VuflowId: {Guid}

  DvrLength: {int}

  MaxBitrate: {int}

  MinBitrate: {int}

  VodEnableDrm: {bool}

  Thumbnail: {string}

  InstantVodStart: {ISO8601 string}

  InstantVodEnd: {ISO8601 string}

  ScheduledProvisionAt: {ISO8601 string}

  ScheduledTerminateAt: {ISO8601 string}

  RemixflowId: {Guid}

  CustomPropertyConfigurationId: {Guid}

  InfrastructureProfileId: {Guid}

  ArchiverflowId: {Guid}

  ArchiverStart: {ISO8601 string}

  ArchiverEnd: {ISO8601 string}

  RefreshIndex: {bool}
  
  AutoExpirePublishingPoints {bool} - Will auto restart the event if all publihsingpoint fail. Default is false.

Note: id is required when updating a specific Event, but optional when adding.

Note: channelId and infrastructureProfileId changes can be ignored if the Event is currently streaming, starting, or provisioning.

Note: all ISO8601 strings can be provided as null if desired.

TagModel Structure:

{
  "id": "d78a3df6-98d2-49d0-b7fa-0f489d2dc3f2",
  "name": "my-tag"
}

Unescaped DrmJson Example:

{
  "drm_provider": "THIRDPARTY",
  "drm_data": [
    {
      "name": "CENC",
      "key_id": "key-id-here",
      "content_id": "content-id-here",
      "widevine_drmspecific": "",
      "widevine_laurl": "widevine-laurl-here",
      "key_iv": "",
      "playready_laurl": "playready-laurl-here"
    },
    {
      "name": "FAIRPLAY",
      "key_id": "key-id-here",
      "key_iv": "key-iv-here",
      "laurl": "fairplay-laurl-here"
    }
  ]
}

Response: 200 OK

PATCH `/event/{id}`¶

Patch update an event by its ID.

Content Type

application/json-patch+json

Request Body:

[
  {
    "op": "replace",
    "path": "/Title",
    "value": "My event title"
  }
]

Response: 200 OK

PATCH `/event/reference/{referenceid}`¶

Patch update an event by its references ID.

Content Type

application/json-patch+json

Request Body:

[
  {
    "op": "replace",
    "path": "/DrmJson",
    "value": "{\r\n  \"drm_provider\": \"THIRDPARTY\",\r\n  \"drm_data\": [\r\n    {\r\n      \"name\": \"CENC\",\r\n      \"key_id\": \"key-id-here\",\r\n      \"content_id\": \"content-id-here\",\r\n      \"widevine_drmspecific\": \"\",\r\n      \"widevine_laurl\": \"http://widevine.entitlement.theplatform.eu/wv/web/ModularDrm/getWidevineLicense\",\r\n      \"key_iv\": \"\",\r\n      \"playready_laurl\": \"https://green.playready.entitlement.theplatform.eu/playready/rightsmanager.asmx?cfg=(kid:120b4b3b4300b8cc753f8dd1cbfcd563,contentkey:NmQ2NGNlNjExNzc1YjIxOTk4N2VkMTU4ZGI3NDZiZDg=,ckt:aesctr)\"\r\n    },\r\n    {\r\n      \"name\": \"FAIRPLAY\",\r\n      \"ask\": \"\",\r\n      \"key_id\": \"key-id-here\",\r\n      \"key_iv\": \"keyiv-here\",\r\n      \"laurl\": \"skd://fairplay.entitlement.theplatform.eu/fpls/web/FairPlay\"\r\n    }\r\n  ]\r\n}"
  }
]

Response: 200 OK

POST `/event/stream/dvrwindowlength/{id}`¶

Update the DVR Window Lenth for the associated live stream to the given Event Id.

Request Body:

  DvrWindowLength: {int}

Response: 200 OK

POST `/event/vuflow/add/`¶

Adds a Vuflow task to an Event (or creates and Event for one if necessary).

Request Body:

TaskEngineJson: {string} - Required. Specify the task you wish to run. 
Id: {Guid} - Optional. Specify an existing ID to set the task on this Event.
EventState: {EventState} - Optional. Specify the state you wish to transition the Event into.
Mp4State: {Mp4State} - Optional. Specify the MP4 state you wish to set on the Event.
RefreshIndex: {bool} - Optional. Specify if you wish to refresh any indexing for this Event.

Response: 200 OK

PUT `/event/{id}/externalupdate/{flag}`¶

Set ExternalUpdate to a given value.

Response: 200 OK

PUT `/event/forcestop/{id}`¶

Use this method to force an event into a stopped state. This function will also force stop the encoder channel running - bypassing the concurrency lock mechanism and removing any existing locks. Should be used as a last resort in case the lock synchronisation becomes out of sync.

Warning: Potentially dangerous as no checks will be made to see if a different Event is running on the associated Channel.

Response: 200 OK

PUT `/event/state/{id}`¶

Update the Event state.

Send 1 (LIVE_UNPUBLISHED) or 2 (LIVE_PUBLISHED) to start the encoder.

Send 4 (STOPPED) to stop the encoder.

See Event States for more information.

Response: 200 OK

PUT `/event/vuflow/protection/{contentId}`¶

Update the Event state with protection level checks.

Typical usage is to change between VOD_PUBLIC and VOD_PRIVATE.

Request Body:

  Protection: {EventState} - the state to change to.

Response: 200 OK

GET `/event/`¶

Get Events, filtered by given parameters.

Query Parameters:

Name	Type	Required	Description
`from`	String	No	ISO8601 DateTime string to include Events scheduled from the given Date.
`to`	String	No	ISO8601 DateTime string to include Events scheduled until the given Date.
`fromModified`	String	No	ISO8601 DateTime string to include Events which have been modified since the given Date.
`toModified`	String	No	ISO8601 DateTime string to include Events which have been modified up to the given Date.
`eventState`	String	No	Comma separated string of Event States to filter to.
`pageSize`	int	No	Number of results to fetch per Page.
`pageNumber`	int	No	Number of the page to fetch.
`order`	QueryOrder	No	The order to sort by, either ASC or DESC. Defaults to ASC.
`room`	String	No	Name of the Room to filter Events on.
`eventType`	String	No	Name of the EventType to filter Events on.
`category`	String	No	Name of the Category to filter Events on.
`channel`	String	No	Name of the Channel to filter Events on.
`tags`	String	No	Comma separated string including Tags to check for on the Events.
`skipEvents`	String	No	Comma separated Guids to omit from the results.
`orderColumn`	String	No	Name of the column to order on (see supported list below).
`search`	String	No	String to search Event properties for.
`noScheduledEnd`	bool	No	Whether or not to only return Events that do not have a Scheduled End value.
`containsVuflow`	bool	No	Whether or not to only return Events which have a Vuflow set.
`publishingPointsMethod`	PublishingPointsMethod	No	Set the method to get the publihsingpoints. "ALL_AVAILABLE" will remove duplictaes and return all, in one call. "SAME_AS_STREAM_SOURCE" will return only those for this stream source.
`noCache`	bool	No	Whether or not to bypass cache. Defaults to False.

Supported Order Columns:

Title
State
DisplayLiveStart
DisplayLiveEnd
EventType
Room
Channel
Vuflow
RefId
ExternalId

Response: 200 OK with an Event collection.

GET `/event/deleted/`¶

Get deleted Events, filtered by given parameters.

Query Parameters:

Name	Type	Required	Description
`from`	String	No	ISO8601 DateTime string to include Events scheduled from the given Date.
`to`	String	No	ISO8601 DateTime string to include Events scheduled until the given Date.
`eventState`	String	No	Comma separated string of Event States to filter to.

Response: 200 OK with an Event collection.

GET `/event/{id}`¶

Get Event by Id.

Query Parameters:

Name	Type	Required	Description
`in`	ISO8601 String	No	ISO8601 DateTime string to be the streaming In point.
`out`	ISO860 String	No	ISO8601 DateTime string to be the streaming Out point.
`audioOnly`	bool	No
`autoStart`	bool	No
`processVideo`	bool	No	Whether or not to return the Video data within the Event response.
`viewUnpublished`	bool	No	Whether or not to return Video data which allows viewing of the LIVE_UNPUBLISHED period.
`streamSource`	StreamSource	No	Specify the StreamSource for fetching from Origin.
`noCache`	bool	No	Whether or not to bypass cache. Defaults to False.

Response:

200 OK and JSON containing the Event object.

or

204 No Content if no Event was found.

GET `/event/reference/{referenceId}`¶

Get Event by Reference Id.

Response:

200 OK and JSON containing the Event object.

or

204 No Content if no Event was found.

GET `/event/external/{externalId}`¶

Get Event by External Id.

Response:

200 OK and JSON containing the Event object.

or

204 No Content if no Event was found.

GET `/event/external/unique/{externalId}`¶

Check if a given ExternalId is in use or not.

Response: 200 OK and the following JSON content:

{
  "IsUnique": true,
  "Value": "externalId-value-here",
  "ValueType": "External ID"
}

GET `/event/reference/unique/{referenceId}`¶

Check if a given ReferenceId is in use or not.

Response: 200 OK and the following JSON content:

{
  "IsUnique": true,
  "Value": "referenceId-value-here",
  "ValueType": "Reference ID"
}

GET `/event/{id}/externalupdate/`¶

Check if the given Event has externalupdate allowed or not.

Response: 200 OK and the following JSON content:

{
  "Id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
  "ExternalUpdateAllowed": true
}

GET `/event/channel/{id}`¶

Gets the currently running Event for a specific Channel Id.

Response: 200 OK and JSON containing the Event object.

GET `/event/clone/{id}`¶

Clone the given Event to create a new one.

Query Parameters:

Name	Type	Required	Description
`ignoreCustomProperties`	bool	No	Whether or not to skip cloning Custom Properties. Defaults to False.
`ignoreChapterPoints`	bool	No	Whether or not to skip cloning ChapterPoints. Defaults to False.
`ignoreChannelProfile`	bool	No	Whether or not to skip cloning Channel Profile. Defaults to False.
`ignoreDocuments`	bool	No	Whether or not to skip cloning Documents. Defaults to False.
`ignorePlayoutProfiles`	bool	No	Whether or not to skip cloning Playout Profiles. Defaults to False.

Response: 200 OK and JSON containing the Event object.

GET `/event/restore/{id}`¶

Restore the Event from a soft-deletion state.

Response: 200 OK

DEL `/event/{id}`¶

Delete an Event by Id.

Query Parameters:

HardDelete: {bool} - Optional. Defaults to false. Set to true to remove all data from the database & servers.

Response: 200 OK

POST `/event/clearcache/`¶

Clear the cache for a given Event Id.

Request Body:

{
  "eventId": "5c08c30b-a444-44a0-b7c8-72cb2e6f4ba4"
}

Response: 200 OK

GET `/event/playoutprofiles/{id}`¶

Gets the Live Playout Profiles associated with the Event with the specified ID. Requires the Live Playout Profile Get permission.

Query Parameters¶

Name	Type	Required
`idsOnly`	bool	No (default: `false`)

Responses¶

Scenario	Code	Body
`idsOnly=false`	`200`	Array of Live Playout Profile objects
`idsOnly=true`	`200`	Array of GUID strings

Example Request¶

/event/playoutprofiles/50e894a0-770f-4b10-843b-9a7340f84655

Example Response¶

[
    {
        "id": "a782bfee-5609-40da-94b6-8e92295c8da4",
        "configurationJson": "{\"manifestFile\":\"clear_profile.isml\", ...}",
        "name": "Clear Profile"
    },
    {
        "id": "053ee005-13ba-4278-b36a-c75c835cfb80",
        "configurationJson": "{\"manifestFile\":\"drm_profile.isml\", ...}",
        "name": "DRM Profile"
    }
]

POST `/event/playoutprofiles/{id}`¶

Sets the Live Playout Profiles to associate with the Event with the specified ID. If the Event is in any one of the Playout States, then a origin manifest sync operation is performed on the Event Channel’s origin server(s) to create/update/remove playout manifests for the new Live Playout Profile collection. Requires the Live Playout Profile Edit permission.

Request Body¶

An array of GUID strings of the Live Playout Profiles to associate with the event.

Responses¶

Scenario	Code	Body
Success	`200`	Array of Origin Manifest Sync Result objects

Example Request¶

/event/playoutprofiles/50e894a0-770f-4b10-843b-9a7340f84655

[
    "9dbabcc5-5802-4b78-af68-85e26e87bdff",
    "232912a3-8a5b-4c23-980c-73238d5b39fd"
]

Example Response¶

[
    {
        "profileId": "9dbabcc5-5802-4b78-af68-85e26e87bdff",
        "eventId": "50e894a0-770f-4b10-843b-9a7340f84655",
        "success": true
    },
    {
        "profileId": "232912a3-8a5b-4c23-980c-73238d5b39fd",
        "eventId": "50e894a0-770f-4b10-843b-9a7340f84655",
        "success": false,
        "errors": [
            "Example error"
        ]
    }
]

EVENTS¶

Event Object¶

Event Collection¶

Supported Actions¶

POST /event/¶

PATCH /event/{id}¶

PATCH /event/reference/{referenceid}¶

POST /event/stream/dvrwindowlength/{id}¶

POST /event/vuflow/add/¶

PUT /event/{id}/externalupdate/{flag}¶

PUT /event/forcestop/{id}¶

PUT /event/state/{id}¶

PUT /event/vuflow/protection/{contentId}¶

GET /event/¶

GET /event/deleted/¶

GET /event/{id}¶

GET /event/reference/{referenceId}¶

GET /event/external/{externalId}¶

GET /event/external/unique/{externalId}¶

GET /event/reference/unique/{referenceId}¶

GET /event/{id}/externalupdate/¶

GET /event/channel/{id}¶

GET /event/clone/{id}¶

GET /event/restore/{id}¶

DEL /event/{id}¶

POST /event/clearcache/¶

GET /event/playoutprofiles/{id}¶

Query Parameters¶

Responses¶

Example Request¶

Example Response¶

POST /event/playoutprofiles/{id}¶

Request Body¶

Responses¶

Example Request¶

Example Response¶

POST `/event/`¶

PATCH `/event/{id}`¶

PATCH `/event/reference/{referenceid}`¶

POST `/event/stream/dvrwindowlength/{id}`¶

POST `/event/vuflow/add/`¶

PUT `/event/{id}/externalupdate/{flag}`¶

PUT `/event/forcestop/{id}`¶

PUT `/event/state/{id}`¶

PUT `/event/vuflow/protection/{contentId}`¶

GET `/event/`¶

GET `/event/deleted/`¶

GET `/event/{id}`¶

GET `/event/reference/{referenceId}`¶

GET `/event/external/{externalId}`¶

GET `/event/external/unique/{externalId}`¶

GET `/event/reference/unique/{referenceId}`¶

GET `/event/{id}/externalupdate/`¶

GET `/event/channel/{id}`¶

GET `/event/clone/{id}`¶

GET `/event/restore/{id}`¶

DEL `/event/{id}`¶

POST `/event/clearcache/`¶

GET `/event/playoutprofiles/{id}`¶

POST `/event/playoutprofiles/{id}`¶