Agent Configuration

after you have downloaded and untarred the zixi esam agent files, you can configure the agent by editing the /zixi/esam linux x64/config json or /zixi/esam linux arm64/config json file the json configuration is made up of six arrays of key/value pairs, which are explained below also see appendix b example config json file docid\ o 74uavfiuqkspw4umxrm agent configuration agent array this array contains startup information port \[integer] the tcp port the agent is listening on this port will be used for unsolicited messages and scte 35 messages coming from the broadcaster sds \[signal decision service] there are two sds services that can be used with esam esni/scte 224 – content switching pois/scte 130 – scte 35 manipulation (see sds terminology docid\ kmh8xypqthz9gvmgaik1g below for an explanation of terms used in this section ) sds configuration array mode \[string] “esni” or “pois” indicating desired service multiple services can be configured by adding an additional sds json array { } within the sds section baseurl \[string] url to send signal processing event messages to note if using both pois and esni it is not recommended to use the same endpoint as each service sends its own signal processing event username \[string] if the sds requires authentication password \[string] if the sds requires authentication zoneidentity – id of output to be switched corresponds to audience in scte 224 type \[string] generally “output” path \[string] full jsonpath https //goessner net/articles/jsonpath/index html#e2 location of desired external id key in output metadata “user data zm external id” is default acquistionpointidentity – id of an output or input to mark where the scte 35 messages were captured corresponds to source in scte 224 type \[string] options include \[“output”,”input”] path \[string] full jsonpath location of desired external id in input/output metadata “user data zm external id” is default altcontentidentity \[string] – id of an input that the zoneidentity will switch to (destination input ) generally, should match path of acquistionpointidentity corresponds to content under viewingpolicy in scte 224 retrydelay \[integer] wait time before retry after api timeout maxretries \[integer] number of retries after timeout broadcaster array the esam agent gathers input and output info as well as triggers switches and inserts scte via the broadcaster api this section outlines communication preferences port \[integer] tcp port hosting the broadcaster service username \[string] broadcaster ui admin username password \[string] broadcaster ui admin password retrydelay \[integer] milliseconds the agent should wait when interacting with the broadcaster api maxretries \[integer] number of attempts the agent should make when interacting with the broadcaster api cachms \[integer] how long the broadcaster input/output list is stored to optimize performance when conducting multiple switches at once redirect array this array details switching options using the redirect client json api abortontimeout \[boolean] allow redirect client api call to abort action if pts detection time runs out seamless \[boolean] perform seamless switch if pts detection times out overwriteifinprogress \[boolean] cancel current api request in favor of new api request with same parameters if false, multiple switches will be queued ptsdetectiontimeoutms \[integer] the amount of time in milliseconds the broadcaster should continue to search in real time for provided pts logger array there are three options to log— console , syslog , file they can be used simultaneously the library is the winston library which has more config info found here https //github com/winstonjs/winston daily rotate file?tab=readme ov file#options console – will post logs to stdout silent \[boolean] false will post logs to the stdout level \[string] sets the log level that should be posted to the stdout options include \[“debug”, “info”, “warning”, “error”] file – will post logs to file level \[string] sets the log level that should be posted to the file options include \[“debug”, “info”, “warning”, “error”] filename \[string] format of filename %date% will use the value assigned to datepattern dirname \[string] directory to write logs to it’s recommended to match the file path with that of the zixi broadcaster logs so they can be accessed in a single place via zen master tunnel without ssh access datepattern \[string] format of datetime string maxsize \[string] max size each file should reach maxfiles \[string] the number for files to keep before cycling syslog will post logs to external syslog server we passthrough parameters from the winston syslog implementation https //www npmjs com/package/winston syslog level \[string] log level \[“debug”, “info”, “warning”, “error”] host \[string] host ip of syslog server port \[integer] syslog communication port protocol \[string] syslog communication protocol log message reference details of all log messages can be found in appendix f esam agent log reference docid\ xfh2a l8vupgr90joip2z zenmaster array this array configures agent to report to zen master or other external system baseurl \[string] – the url where to post scte 35 messages and notifications of content switches (if using zen master, https //zen zixi com https //zen zixi com ) apikey \[string] key used for authentication to external system added as value to “x api key" in request headers (if using zen master, configuration > api keys in your zen master account) switchtargetpath \[string] uri where the notifications can be sent in the baseurl (if using zen master, “api/scte224/targets”) input & output configuration parameters acquisition point identity – the id associated with any scte 35 message sent to a decisioning service included in both spes and spns, this can correlate to a zixi broadcaster input or output depending on how the schedule is set up and will generally correspond to the \<source> attribute in an esni media or mediapoint zone identity – part of the spn for the switching component, this is the id of the zixi output or esni audience that will be switched alt content identity – part of the spn for the switching component, this is the id of the input that will be switched to a zixi output or zone identity and corresponds to the \<content> in an esni schedule’s viewingpolicy basic configuration using zen master esni mapping sources to schedule in zen master, create a failover source containing desired source, and in the advanced section, enter an external id that corresponds with source or content ids in the external schedule (failover source does not require two components they are just used in this case as a variable element that is written to the broadcaster) create a passthrough channel for the source in the esam agent config file, set acquisitionpointidentity and altcontentidentity types to input and paths to user data zm external id mapping targets to schedule in zen master, create a target and in the advanced section, enter an external id that corresponds to the audience id (or zip/vird/etc) in the external schedule in the esam agent config, set zoneidentity type to output and path to user data zm external id pois in zen master create a failover source containing desired sources, and in the “advanced” section, enter an external id (failover source does not require two components in this case, it is just used as a variable element that is written to the zixi broadcaster) create a passthrough channel for the source create a target and in the “advanced” section, choose an external id and enter a pois latency offset this value can be zero, but it establishes that this output should receive pois scte conditioning if a value is entered, this will offset the pois modification path to allow for api latency note that the external id is only required if doing pois modification on the inputs in the esam agent config file, set acquisitionpointidentity path to user data zm external id if acquisitionpointidentity is on the input, all pois enabled targets connected to the channel with matching external id will receive pois conditioning if acquisitionpointidentity is on the output, only scte on targets with matching external id will be conditioned broadcaster only deployments (no zen master) the esam agent references input/output metadata to match unique identifiers for the below instructions use the /edit stream json and /edit output json endpoints with parameter userdata= {“zm external id” ”desired id”} for more information on api, refer to zixi broadcaster api manual available on the custom portal acquisitionpointidentity in the agent config json, set type to either input or output depending on the external sds set up for path , we recommend the default, user data zm external id this id represents where the scte 35 messages were captured, or the output connected to the input that the scte 35 messages were captured on this generally equates to the \<source> attribute in a 224 schedule for pois this would be that input/output that will receive manipulation using the broadcaster api, update the user data zm external id field to match the source ids referenced by the sds on desired inputs/outputs that should be referenced by the sds zoneidentity zoneidentity is often on the output in the config, set type to output for path , we recommend the default, user data zm external id using the broadcaster api, set the user data zm external id field to match output/audience id’s referenced by the sds altcontentidentity there is no ‘type’ for altcontentidentity as it will always be an input in the config, set ‘path’ to use the same field as acquisitionpointidentity using the broadcaster api, update the user data zm external id field to match the content ids referenced by the sds on desired inputs or outputs that should be referenced by the sds (if there are some sources that are not included in acquisitionpointidentity list) sds terminology esam terminology and how it relates to zixi, scheduling and pois signal processing event (spe) – this is the xml message that is sent to the decisioning service when triggered by a relevant scte message signal processing notification (spn) – this is the xml message that is returned from a decisioning service outlining any stream switches or scte 35 manipulation that should occur unique components of the spe/spn >acquisition point identity – the id associated with any scte 35 message sent to a decisioning service included in both spes and spns, this can correlate to a zixi broadcaster input or output depending on how the schedule is set up and will generally correspond to the \<source> attribute in an esni media or mediapoint zone identity – part of the spn for the switching component, this is the id of the zixi output or esni audience that will be switched alt content identity – part of the spn for the switching component, this is the id of the input that will be switched to a zixi output or zone identity and corresponds to the \<content> in an esni schedule’s viewingpolicy authentication authentication is handled in the config file as user and password parameters the credentials are added to the sds endpoint url with apache basic authentication https //developer mozilla org/en us/docs/web/http/authentication#access using credentials in the url communication methods there are two ways the esam agent communicates with an external sds solicited – @matchsignal the esam agent requests a notification message from the sds on what to do when the esam agent is provided a scte 35 message from the broadcaster the esam agent will make an http post to the sds (at the url provided in the config file) and await a response within the same http connection in esni/scte 224, this is called matchsignal unsolicited – @matchtime the sds reaches out to the esam agent without prompting from the agent as part of the setup with the sds, the ip of the broadcaster, the port hosting the esam agent, and a list of input and output id’s must be provided to the sds to allow them to send messages in esni/scte 224, this is called matchtime special note notifying sds of esam enabled inputs and outputs to facilitate interaction with an sds, zixi has added an external id metadata field in general, the external id that is used to identify esam enabled inputs and outputs should match the source, content, and audience ids used in the sds if the sds partner is planning to send unsolicited messages it is important to notify them of all the available input and output external id’s that can be switched (or manipulated)