Clarification on IS-08 activation response json schema

[VenkateswaranJ]

https://github.com/AMWA-TV/is-08/blob/v1.0.x/APIs/schemas/activation-response-schema.json#L13-L22

"mode": {
      "description": "Mode of activation: immediate (on message receipt), scheduled_absolute (when internal clock >= requested_time), scheduled_relative (when internal clock >= time of message receipt + requested_time), or null (no activation scheduled).",
      "anyOf": [{
        "type": "string",
        "enum": [
          "activate_immediate",
          "activate_scheduled_absolute",
          "activate_scheduled_relative"
        ]
      }, {
        "type": "null"
      }]
    }

In the above activation response schema, the description for mode tells that return null (no activation scheduled) but it should be described as below isn't it?

On the immediate activation, the response for the post request should be activate_immediate but subsequent Get should set the mode value to null

[garethsb]

In this aspect, I think this is a difference from IS-05 primarily because there is no equivalent of the Connection API /staged endpoint. So I think the wording is correct.

The Behaviour spec says "Immediate activations MUST NOT appear in the activations list, as they are carried out upon arrival." Therefore, the only place the activation object appears is (1) in the PATCH response and then (2) in the /map/active endpoints, which is broadly equivalent to the IS-05 /active endpoint activation. That endpoint should show "activate_immediate" and the activation_time of the immediate activation.

[VenkateswaranJ]

That endpoint should show "activate_immediate" and the activation_time of the immediate activation.

Then when should I respond with null? Because if it's there in the schema then there should be a scenario where we need to respond with null as activation mode isn't it?

[garethsb]

Then when should I respond with null?

When there hasn't been any activation since last reboot, for example.

[VenkateswaranJ]

That makes sense, Correct me if I'm wrong in the below scenario,

I have the below activation post request,

{
	"mode": "activate_scheduled_relative",
	"requested_time": "100:0"
}

So after 100 seconds, I need to respond with the below value in the /map/active endpoint.

{
	"mode": "activate_scheduled_relative",
	"requested_time": "100:0"
	"activation_time": "Timestamp when the activation takes place"
}

Now if the I/O map changed in the underlying device for some reason then I need to respond with the latest state of map entries at the /map/active endpoint but still keep the activation_response part as it is (Until any other activation I receive).

Am I right?

[garethsb]

Now if the I/O map changed in the underlying device for some reason

This is a good point. I think the behaviour you propose is OK, but it might be better to either set the activation mode to activate_immediate with the activation_time of when the underlying channel map was changed (or null, I need to double check this point), or set the properties to null when it happened?

[VenkateswaranJ]

Maybe I'm missing something in the point of control software, but why don't we just remove the activation-response-schema field from map-active-response-schema

instead of this,

{
    "activation": { "$ref": "activation-response-schema.json" },
    "map":{
      "allOf": [{
        "$ref": "map-entries-schema.json"
      }, {
        "minProperties": 1,
        "maxProperties": 1
      }]
    }
}

like this?

{
    "map":{
      "allOf": [{
        "$ref": "map-entries-schema.json"
      }, {
        "minProperties": 1,
        "maxProperties": 1
      }]
    }
}

So the active endpoint always returns what's the current state in the underlying device.

Now the question is, How does the control software know whether the scheduled activation got applied to the underlying device or not?

I'm not sure, But two things come to mind,

1. /map/activations/{activationId} should not only hold the list of pending activations but also the list of activations that are already applied in the underlying device (along with status - success or fail). But how many or how long do we need to hold the past activations?

2. If we have an endpoint like /map/activations/{outputId} similar to /map/active/{outputId}(but this only holds the current state of output). Then the Get request on /map/activations/{outputId} will return the below thing

{
	"pending": {
	    "activation_id": { ^[a-zA-Z0-9\-_]+$ },
	    "activation": { "$ref": "activation-response-schema.json" },
	    "map":{
	      "allOf": [{
	        "$ref": "map-entries-schema.json"
	      }, {
	        "minProperties": 1,
	        "maxProperties": 1
	      }]
	    }
	},
	"last_activation":{
	    "activation_id": { ^[a-zA-Z0-9\-_]+$ },
	    "error": {"$ref: error.json"} // this can be null
	}
}

Both pending and last_activation is not mandatory field, for example, the output may return an empty json if there is no pending or last_activation happened in that particular output.

1. Each output can have 0 or 1 pending activation (we will get a Lock error if we try to schedule more than one activation for the same output)
2. Each output can have 0 or 1 last activation status.

I thought informing the client software (or nmos user) about the status of scheduled activation in a clear way will increase the usability.
For example, in IS-05 we are informing the client software about the scheduled activation status via version change in the IS-04 registry but I'm not sure whether it's an effective way of doing it, because of below two reasons

1. IS-05 should be usable stand-alone, isn't it (even without IS-04 or Registry)?
2. So as per the current workflow, the client software has to subscribe to the registry and then it has to expect some version change for that particular sender or receiver on the exact scheduled activation time? what happens if the version change happened because of some other reason instead of the IS-05 patch?

I understand the core purpose of scheduled activation is to `execute a group of activation requests at once, but the client software (or even the nmos user) somehow needs to know clearly what happened to the activation that I scheduled.

[garethsb]

You're making a different point now, right?
And proposing done changes in a future version of IS-08?

So the active endpoint always returns what's the current state in the underlying device

This is already true. It is "rule zero" of NMOS APIs, "reflect the current configuration of the underlying system".

In IS-08 /map/active, the activation object shows the last one that was applied. I think this should be the last activation whether made via this API or for other reasons, but I agree the spec is not clear on this.

As you said, the IS-05 requirements for interoperability with IS-04 and the version mechanism mean a Controller can get notifications when any changes are made for whatever reason. This is true when a Registry is in use and also via the mDNS ver_ TXT records in peer-to-peer mode.

Is it useful for a Controller to know when their specific scheduled activation was applied? I think not very, since it could have been immediately followed by another activation via the API or change to the config in the underlying system by other means. If a Controller wants a specific state to be maintained over a specific period of time, it needs to monitor all state changes to that resource over that time period.

[VenkateswaranJ]

This is already true. It is "rule zero" of NMOS APIs, "reflect the current configuration of the underlying system".

In IS-08 /map/active, the activation object shows the last one that was applied. I think this should be the last activation whether made via this API or for other reasons, but I agree the spec is not clear on this.

Let's say the client software scheduled a list of activations, how does the client software know Activations that are successful & Activations that are failed?

Or in other words, What's the use of activation-response-schema in the /map/active/ response?
This only reflects the state of the last activation request, but there may be a list of activations got failed before this request. Do we silently ignore those failed requests?
Because without activation id it's quite complicated for the client software to decide what happened to the activation request with ID XYZ.

Is it useful for a Controller to know when their specific scheduled activation was applied? I think not very, since it could have been immediately followed by another activation via the API or a change to the config in the underlying system by other means. If a Controller wants a specific state to be maintained over a specific period of time, it needs to monitor all state changes to that resource over that time period.

If the controller software doesn't need to know about the status of scheduled activations then why do we need activation-response-schema in the active endpoint? because it won't help the controller in any way, isn't it?

I'm just trying to get the use case for the activation-response-schema in the /map/active/ endpoint.

[garethsb]

I agree with you, it's just informative/debugging. Same applies to IS-05 /active endpoint.

[VenkateswaranJ]

It's just informative/debugging

Can we place this in the schema, something like below

The above image clearly tells that the GET request on IS-04 Registration API is only for debugging, so the client software only uses that for debugging instead of creating any trustful state inside the app with that info.

If I have something like that in the /map/active response then I wouldn't even create this GitHub thread.

Or explain this in the Behaviour page of the spec, so that both nmos node implementer and client software implementer will be on the same page.

[garethsb]

👍 Will discuss in @AMWA-TV/nmos-architecture-review group.

[peterbrightwell]

Architecture Review Group review: place on backlog

[garethsb]

ARG: propose to add a sentence or two in https://github.com/AMWA-TV/is-08/blob/v1.0.x/docs/Behaviour.md#activation-requests after...

Once an activation has been completed the resulting changes to the map MUST be reflected in the active endpoint. The activation object in the active endpoint MUST contain the details of the last activation to have taken place.

The Behaviour documentation also says...

it is important that the channel mapping behaviour of the underlying Device is reflected in the API at start-up.

We think the required behaviour is actually more general than this, that the API always reflects the current channel mapping behaviour of the underlying Device, so I suggest adjusting that sentence first.

For reference, the IS-05 equivalent text is...

The /active endpoint reflects the current running configuration of the underlying Sender or Receiver.

My suggested additional sentences:

Changes to the underlying Device's channel mapping behaviour (whether initiated by IS-08 or not) are reflected immediately into the Active Map map. Therefore the action of the most recent activation (or any previous activation) can have been overwritten. The only certain way to determine if the current behaviour is what the Client requires is to examine the map.

If we could add normative language we might insist that changes not initiated by IS-08 caused the activation object to be reset (all null values), so that a Client could determine whether the last change was the most recent one they expect (based only on activation_time though, not activationId). However, we can't do this in a patch revision. (And there is also no such language in IS-05.) On balance, I think this is therefore best left as-is.