API ReferenceGuides

CML Structure

CML files, when consumed by hosted workflows, MUST be formatted as VALID XML. An invalid XML format is the primary issue encountered when formatting CMLs for both Vantage and Vantage Hosted Workflows.

In particular, when using a pre-signed URL, the pre-signed URL often contains characters that are not natively capable of being expressed in XML directly via copy/paste mechanics.

For example, consider the following signed URL:

<https://presignedurldemo.s3.eu-west-2.amazonaws.com/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJJWZ7B6WCRGMKFGQ%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180210T171315Z&X-Amz-Expires=1800&X-Amz-Signature=12b74b0788aa036bc7c3d03b3f20c61f1f91cc9ad8873e3314255dc479a25351&X-Amz-SignedHeaders=host>

NOTE: The intent of this document is not to provide instruction into the use of Presigned URLs. This document exists to provide a guide as to how URLs need to be handled/formatted inorder to make use of them within CML.

For reference, a Presigned URL allows temporary access to a piece of content which exists in cloud storage for a prescribed amount of time.

The obvious way to utilize the Presigned URL above within a CML file is to simply copy and paste this into the CML file being constructed:

<Composition xmlns="Telestream.Soa.Facility.Playlist"\>
	<Source identifier="1"\>
	<File
		location="https://presignedurldemo.s3.eu-west-2.amazonaws.com/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJJWZ7B6WCRGMKFGQ%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180210T171315Z&X-Amz-Expires=1800&X-Amz-Signature=12b74b0788aa036bc7c3d03b3f20c61f1f91cc9ad8873e3314255dc479a25351&X-Amz-SignedHeaders=host"/\>

	</Source\>
	<Sequence layer="1"\>
		<Segment\>
		<Video source="1"/\>
		</Segment\>
	</Sequence\>
</Composition\>

The problem with this is that since the path value contains characters which are not natively supported due to the character set restrictions of XML (namely the ‘&’ character); this would represent an ILLEGAL XML file.

If this input was sent to a hosted workflow; the result would be a job FAILURE due to the inability to parse such an input. The details of such a submission would appear similar to:

1243

To correct this, the offending PATH values which contain the illegal XML characters must be properly escaped.

Escaping is the process of translating characters which are RESERVED in XML into their corresponding XML valid entries.

  • ' is replaced with &apos;
  • " is replaced with &quot;
  • & is replaced with &amp;
  • < is replaced with &lt;
  • > is replaced with &gt;

An easy way to get an escaped version of Presigned URL is to make use of a free site which performs this translation, eg:

https://www.freeformatter.com/xml-escape.html#ad-output

Using this site, once can input the original Presigned URL:

<https://presignedurldemo.s3.eu-west-2.amazonaws.com/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJJWZ7B6WCRGMKFGQ%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180210T171315Z&X-Amz-Expires=1800&X-Amz-Signature=12b74b0788aa036bc7c3d03b3f20c61f1f91cc9ad8873e3314255dc479a25351&X-Amz-SignedHeaders=host>

And then translate this to the properly ESCAPED version of the same URL:

<https://presignedurldemo.s3.eu-west-2.amazonaws.com/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&amp;X-Amz-Credential=AKIAJJWZ7B6WCRGMKFGQ%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&amp;X-Amz-Date=20180210T171315Z&amp;X-Amz-Expires=1800&amp;X-Amz-Signature=12b74b0788aa036bc7c3d03b3f20c61f1f91cc9ad8873e3314255dc479a25351&amp;X-Amz-SignedHeaders=host>

Notice that the process of escaping this string has turned the illegal XML character ‘&’ into the legal XML sequence: &

This string can then be embedded into a CML file:

<Composition xmlns="Telestream.Soa.Facility.Playlist"\>
	<Source identifier="1"\>
	<File
		location="https://presignedurldemo.s3.eu-west-2.amazonaws.com/image.png?X-Amz-		Algorithm=AWS4-HMAC-SHA256\&amp;X-Amz-Credential=AKIAJJWZ7B6WCRGMKFGQ%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&amp;X-Amz-Date=20180210T171315Z&amp;X-Amz-Expires=1800&amp;X-Amz-Signature=12b74b0788aa036bc7c3d03b3f20c61f1f91cc9ad8873e3314255dc479a25351&amp;X-Amz-SignedHeaders=host"/\>

	</Source\>
	<Sequence layer="1"\>
		<Segment\>
		<Video source="1"/\>
		</Segment\>
	</Sequence\>
</Composition\>

And this file would successfully be consumed by a Vantage Hosted Workflow.

Updated over 2 years ago