Skip to main content
The ingestAutomationLinkData mutation feeds AutomationLink from the cloud side. You send the current and upcoming items to a station, VRA Cloud hands them to the Core of each targeted studio, and the Core publishes them exactly like a locally linked radio automation. Use it when the automation runs outside the studio network, in a cloud playout system for example, and cannot post to the Core Control API or the generic HTTP link.

​
How it works

  1. Your automation calls ingestAutomationLinkData with the station, optionally one studio, and the current and upcoming sets.
  2. VRA Cloud normalises each item and sends the sets to the Core of every targeted studio over the studio bus.
  3. The Core publishes the items as now playing and upcoming, runs Item Groups and updates the studio state.
  4. For MUSIC items without music_meta, VRA Cloud looks up Music Track Meta in the background and sends the enriched sets a moment later.
The studio needs a running Core. The Core owns the AutomationLink state, so ingested data reaches visuals, the Live Switcher and the studio dashboard through the same path as any other radio automation.

​
Authentication

Authenticate as a Machine User of the station, or as a cloud user who has the station active. A machine user bound to another station is rejected with Not authorized for this station.

​
Targeting studios

  • station_id is required.
  • studio_id targets one studio of the station. Omit it to send the same sets to every studio of the station.
  • Omit current or upcoming to leave that set untouched on the Core. Send an empty list to clear it.

​
Items

Each item in current and upcoming follows the RadioAutomationItem shape the Core uses for every automation:
  • id - unique identifier from your automation. Use an md5 of artist and title if your system has none. The Core uses it to detect a new item, so a changed id means a new track.
  • title and artist - the display values. Both must be at least 2 characters for Music Track Meta lookup.
  • type_identifier - your automation’s own type code for the item, like JINGLE, SWEEPER or a numeric item type. Item Group conditions can match on it.
  • category - MUSIC, TRACK, STATION or UNKNOWN. Defaults to MUSIC. Only MUSIC items are enriched.
  • timestamp - start of the item as a datetime with offset, normalised to UTC.
  • duration and offset - in milliseconds.
  • end_timestamp and completed - mark an item that already ended.
  • igroups - item group identifiers you set yourself. Leave it out to let the Core match your Item Groups. Read that section before you send it.
  • meta - free-form source metadata like item codes, bpm or key, as a JSON encoded string. Stored as the item’s meta string and available in visuals.
  • music_meta - artist, title and album details you already have. Any value here, even a cover URL alone, counts as supplied and skips the Music Track Meta lookup.
meta is a JSON scalar and must be sent as a JSON encoded string, not as a GraphQL object literal. Write meta: "{ \"item_code\": \"M-48213\" }" or pass the string through a variable. An object literal is rejected by the schema.

​
Item groups

Item Groups are configured per station under Settings → Outputs → Item Groups. Each group has an identifier, a category, a match type and conditions on item fields. Outputs, playable items and conditions use the identifier to react to the kind of item on air. The Core assigns them, not VRA Cloud. For every current and upcoming item, the Core checks the item’s igroups first:
  • Empty or left out. The Core runs every Item Group of the station against the item. Each group whose conditions match adds its identifier to igroups and sets the item’s category to the group’s category.
  • Not empty. The Core uses your list as it is and skips Item Group matching for that item.
So there are two ways to classify an item. Pick one per integration. Let the Core match (recommended). Send the fields your automation already has and leave igroups out. Conditions match on any item field, like type_identifier, title, artist or category, and on every key inside meta. A condition on item_code matches meta: "{ \"item_code\": \"J-001\" }". Changing a group in VRA then works without touching your integration. Set igroups yourself. Useful when your automation already knows the group and no field describes it. Keep in mind:
  • Your list replaces matching completely. Sending one identifier means no configured group matches that item, not even the ones whose conditions would.
  • The group’s category is not applied. Send category yourself, or the item stays MUSIC and gets a Music Track Meta lookup.
  • Identifiers are compared as exact text and are not checked against the station’s groups. Use the identifier as it shows in Item Groups, which is uppercase with underscores, like STATION_ID. A typo or a renamed group fails without an error.
Send type_identifier and let an Item Group match on it. That is how every built-in radio automation link classifies items.

​
Example

Push one current track, a station ID and two upcoming tracks to a single studio. The current item ships its own cover and artist image, so VRA Cloud does not look it up. The station ID carries a type_identifier for an Item Group to match on and is not enriched. The two upcoming tracks have no music_meta and are enriched in the background.
Response:
  • studios - number of studios the sets were sent to.
  • enrichment_queued - number of unique MUSIC items queued for Music Track Meta lookup. The enriched sets follow on the same path once the lookup finishes, so expect a second update on the studio a few seconds later.

​
Clearing the current item

Send an empty current list when the automation stops or goes to a non-music item you do not want on screen. upcoming stays as it was.