Add result to an Action

[etwobben]

Type of request

• I'd like to add something to the OTM 5 spec
• I'd like to change something in the OTM 5 spec

Is your feature request related to a problem?
In the lifeCycle field of an Action we can set at which step in the process an action is, but we won't know if that step was succesfull or not. For example for an Load or Unload action, the action can be realized, but the package is not delivered.

Describe the solution you'd like
Two new fields in the Action. These can only be used in the realized lifecycle.

• result (enum value of "succeeded", "failed" and "partially_succeeded").
  Partially is needed when some of the goods can be delivered, but not all. For example if a good is damaged or not present in the truck.
• result_description.
  To communicate what the reason is for that result. (for example, nobody present, damaged goods, etc)

Describe alternatives you've considered
Ofcourse ExternalAttributes is an option, but this seems such a "basic" thing that it should be added to the base element.

Additional context
None

[bmeesters]

Hello @etwobben, thank you for your contribution.

We have talked about adding an optional result to all actions types before and are in favor. However our original idea was to not make it an enum (like your proposal), but to make it a record with additional information including the enum.

For example:

{
  "actionType": "load",
  "consignment": { ... },
  "result": {
    "status": "failed",   <-- the enum you proposed
    "remark": "somebody dropped the goods and they broke",
    "code": 1234,
  },
  .. etc
}

The reason to make it an object instead of just the status is so you can actually provide an explanation. Preferably, we would also add some status code, so the different results can be grouped (free text fields make this hard). However we did not yet get to enumerating the possible status codes we would like to provide.

We can of course already start with discussing everything else that needs to be in there.

IMO we should add:

1. The status, which can be success, failed or partially succeeded.
2. The remark on the why, usually only filled when something is failed or partially succeeded.
3. the status code, similar to HTTP codes so we can easily say something like "damaged goods", "nobody home", etc.

Any other data I am forgetting now?

[etwobben]

Thanks for the quick reply @bmeesters !

I was also leaning towards an object, so your proposal is fine with me.

In regards with your code field. This is an enum value, because its a predefined list of possible values. Otherwise its impossible to communicatie it with other organizations. Why make it a number here, instead of a string representation like other enums in OTM?

[bmeesters]

I agree, a string enum would be better for the code. I'll need to discuss this with some other people, but I'll get back to you (likely on Thursday since we have a meeting planned then where we can discuss this).

[etwobben]

That would be great!

I have actually 2 other question that are somewhat related to this.

• In the cause of a partially succeeded action, and not all goods could be delivered or picked up, the remainder needs to be plannend again. This results in a new consigment with a new actions, and goods that are leftover. We would like to somehow connect that new consigment with the old (origin) consigment to monitor the progress of the original consigment. Any ideas for this?
• The consigment can have a status of completed or cancelled, but in the case of a failed action, the consigment itself should also be marked as failed.

Perhaps both can be combined; in the case the consigment has a failed status, a follow up consigment can be set.

[bmeesters]

Yes, we actually had similar problems when a requested consignment was too big for a single vehicle and had to be divided over two new consignments. It would be nice if you can somehow reference the original consignment in the two new ones. I think we can add a new field to consignment relatedConsignments (or something similar) where you can associate other consignments. You can then use the description attribute on each association to describe the relationship. What do you think?

Regarding a new status failed. I am not sure whether that will be confusing with cancelled. In principle you can cancel the first consignment, create a new one and then refer from the new to the old consignment right?

[etwobben]

Your usecase is one that's also one of our more difficult consigments. A colleague of my already described a few scenario's that we try to fit in OTM in the discussion forum (see link).

The relatedConsigments can work I think. Not sure if a description field is sufficient to describe the "why" its related. Perhaps a enum field is more descriptive (for example; partially failed, oversized, follow up, etc). Not sure which values we need, but otherwise we have to parse the description field to filter the "why".

There is a difference is something is cancelled or failed. Cancelled is before a trip even started (from the client; we no longer need you to deliver/pickup), and failed indicates we tried to complete the consigment, but did not succeed (nobody home, traffic jams, truck motor issues, etc).

[bmeesters]

Not sure if a description field is sufficient to describe the "why" its related. Perhaps a enum field is more descriptive (for example; partially failed, oversized, follow up, etc).

Yes I agree that a text field is not ideal. However the association is a generic field that is also used to associate vehicles to trips, goods to consignments, locations to stops, etc. So if we add a 'relation' enum it has to make sense for all of those. We still can of course, but some relation types will not make sense for some relations (e.g. oversized will not make sense when coupling a vehicle to a trip) and the documentation would need to be very clear about this as otherwise it might do more harm than good.

There is a difference is something is cancelled or failed.

I agree, though the difference can be quite subtle. With the use cases where we work cancels can also happen on-trip. Though I suppose the big difference is intentional vs non-intentional.

I'll be sure to also discuss it next Thursday.

[etwobben]

Yes I agree that a text field is not ideal. However the association is a generic field that is also used to associate vehicles to trips, goods to consignments, locations to stops, etc. So if we add a 'relation' enum it has to make sense for all of those.

That's not entirely correct, because the association for an actor has an extra field roles that is not in any of other associations. In a way this situation is the same as that one, as its describe the why its associated more clearly than only a text field.

[bmeesters]

Yes that is true, but how many of these unique new relation type of fields do we need to add? IMO it is a bit of a slippery slope by creating more and more specialized fields for different associations. We might have already gone to far with the actor roles. I am a little bit hesitant to add even more. Because if we add those for consignments, why not also add them for locations, or goods, or vehicles?

[bmeesters]

I am not saying we shouldn't do it, just that we need to be careful. It might be worth it after all. Lets see what other parties have to say.

(We might want to split this conversation in a new change request, to ensure that adding results to actions can be evaluated separately)

[bmeesters]

The result is accepted for OTM5.3 I'll be working on a proposal for the different codes we can use. I'll also make a new change request for the related consignments so we can discuss that separately.

[bmeesters]

I opened a new change request for the relatedConsignments: #32

So this ticket can focus on adding results to actions.

[bmeesters]

So updating my previous proposal:

{
  "actionType": "load",
  "consignment": { ... },
  "result": {
    "status": "failed",  // alternatives: succeeded, partiallySucceeded
    "remark": "somebody dropped the goods and they broke",
    "reason": "damage",
  },
  .. etc
}

The reason would be an enum and only necessary on failed or partiallySucceeded. I think damage, deficiency and notAvailable (for example for delivery somebody was not home, or the goods could not be loaded because the party lost them somewhere in the warehouse) could be a good start for the reasons. Not sure if I am missing anything?