Validate and formalize connector message format.

Currently, the format of messages expected and put out by connectors is this:

{
    id: string,
    attachments: {},
    body: {
        data: {},
        meta: {
            recordUid: string,
            oihUid: string,
        }
    },
    headers: {},
    metadata: {},
  }

This is something a legacy format, as this was the one used by the elasticio platform at the time. Some connectors still use the function newMessageWithBody() supplied by an elasticio dependency to create this function. Others use a more lightweight inbuilt helper function to achieve the same (e.g. https://github.com/openintegrationhub/placetel-connector/blob/578311b1049430ce1f32037d2c74582440cf472c/lib/utils/helpers.js#L88)

However, in practice, only the body field is ever really used. There may be a future use-case for the attachments field, but so far it is not used by any connector. As such, we should re-evaluate which fields are actually relevant and, if necessary, adjust the format to a simpler version. The finalized format, whether any changes are made or not, should then be explicitly detailed in documentation.

---

Acceptance Criteria:

• Discuss current message format
• If format is changed: Adjust current connectors to use new format
• Update documentation

---

Definition of Done

[weberjm]

As you mentioned, this format is derived from the legacy implementation of elastic.io messaging. I have had trouble finding specific descriptions in either OIH or Elastic documentation to clarify the full usage of each field. The closest I came was this page, regarding the ability to use the attachment field in an elastic message.

The first item that pops out at me from the above comment, is that we have both message metadata (metadata) and body metadata (meta) parameters. While it is true that we could have metadata at both levels, would it not be more concise to say that any field at the top level is a metadata field, used for messaging implementation, except for the attachment and body parameters?

There are two questions we need to answer to come up with a solid solution here:

1. Which fields are needed to fully pass data through a flow, including flexibility for currently unrealized use cases?
2. Where is the separation of responsibility for providing each element? For instance, the trigger or action function should not be responsible for properly assembling a message structure. At most, it should know about data/body fields and about attachments. The message packaging should be handled by the ferryman.

[SvenHoeffler]

Most existing connectors have been migrated to the new format. Moving this to review pending further testing and potential bugfixes.