Response Summary Message Part

Whenever a Message’s state changes, a Response Summary Message Part gets added to the Message (or updated within the Message if it already exists).

Each Message Part within your Message could have its own Response Summary Message Part. For example, a Carousel of 4 Choice Messages is represented with:

  • Carousel Root Message Part: application/vnd.layer.carousel+json
    • Choice 1’s Message Part: application/vnd.layer.choice+json
      • Choice 1’s Response Summary: application/vnd.layer.responsesummary-v2+json
    • Choice 2’s Message Part: application/vnd.layer.choice+json
      • Choice 2’s Response Summary: application/vnd.layer.responsesummary-v2+json
    • Choice 3’s Message Part: application/vnd.layer.choice+json
      • Choice 3: User hasn’t made a selection, so there is not yet a Response Summary Message Part
    • Choice 4’s Message Part: application/vnd.layer.choice+json
      • Choice 4: User hasn’t made a selection, so there is not yet a Response Summary Message Part

Structure of a Response Summary

{
  "mime_type": "application/vnd.layer.responsesummary-v2+json;role=response_summary;parent-node-id=" +
    UUID_OF_PART_THIS_IS_FOR,
  "body": JSON.stringify({
    "layer:///identities/frodo-the-dodo": {
      "color": {
        "adds": [
          {"ids": ["8yFb5j"], "value": "red"},
          {"ids": ["Zjf8Ac"], "value": "blue"}
        ],
        "removes": ["KO2nmx"]
      },
      "likes": {
        "adds": [
          {"ids": ["b295KaJ"], "value": true}
        ],
        "removes": []
      }
    }
  })
}

MIME Type

  • The MIME Type for a Response Summary is currently application/vnd.layer.responsesummary-v2+json; the v2 may get incremented as the XDK evolves.
  • The role for a Response Summary is response_summary
  • The parent-node-id is set to the UUID portion of the Message Part ID of the Part that this is managing state for

Identity IDs

Any number of users may make state changes to a Message.

Within the Message Part body, values are indexed by the Identity IDs of the users who have made state changes. When a Response Message is sent, the Message’s sender field is used to update this structure, either adding to an existing user’s state, or adding a new user to the structure.

{
  "body": JSON.stringify({
    "layer:///identities/identity1": {state...},
    "layer:///identities/identity2": {state...},
    "layer:///identities/identity3": {state...}
  })
}

Each state is namespaced to the sender of that state change. This insures that a user can not execute state changes upon other users.

State Names

Within each Identity in the structure is a set of states indexed by state name:

{
  "layer:///identities/identity1": {
    "state1": {},
    "state2": {}
  },
  "layer:///identities/identity2": {
    "state1": {},
    "state3": {},
  },
  "layer:///identities/identity3": {
    "state3": {},
    "state4": {}
  }
}

State Adds Array

Each add operation from a Response Message adds a value/id pair to the state structures:

The following operation:

[{
  "operation":"add",
  "type":"Set",
  "value":"red",
  "name":"state1",
  "id":"8yFb5j"
}]

Results in the following struture:

{
  "layer:///identities/identity1": {
    "state1": {
      "adds": [
        {"ids": ["8yFb5j"], "value": "red"}
      ],
      "removes": []
    },
  }
}

Further values may be added:

[{
  "operation":"add",
  "type":"Set",
  "value":"blue",
  "name":"state1",
  "id":"Zjf8Ac"
}]

Results in:

{
  "layer:///identities/identity1": {
    "state1": {
      "adds": [
        {"ids": ["8yFb5j"], "value": "red"},
        {"ids": ["Zjf8Ac"], "value": "blue"}
      ],
      "removes": []
    },
  }
}

Attempts to add another red will not add a new entry to the adds array, but will instead add additional ids that must be removed using remove operations before that value goes away:

[{
  "operation":"add",
  "type":"Set",
  "value":"red",
  "name":"state1",
  "id":"abcdef"
}]

Results in the following struture:

{
  "layer:///identities/identity1": {
    "state1": {
      "adds": [
        {"ids": ["8yFb5j", "abcdef"], "value": "red"},
        {"ids": ["Zjf8Ac"], "value": "blue"}
      ],
      "removes": []
    },
  }
}

Reissuing an id will be ignored:

[{
  "operation":"add",
  "type":"Set",
  "value":"red",
  "name":"state1",
  "id":"abcdef"
}]

Will not add an additional id for red.

State Removes Array

The removes array is an array of id values that are no longer valid or were never valid.

There are three ways that an id gets added to the removes array:

  1. The operation could not be performed; the operation’s id is added to removes
  2. A remove operation is performed to explicitly remove an id
  3. An add operation is performed, any prior value is removed and its id added to removes

Operation could not be performed

Consider an add operation where type is FWW (First Writer Wins), and there is already a value. If our intial state is:

{
  "layer:///identities/identity1": {
    "state1": {
      "adds": [
        {"ids": ["Zjf8Ac"], "value": "blue"}
      ],
      "removes": []
    },
  }
}

The following operation will be flagged to all parties as invalid and to be ignored by adding its id to removes:

[{
  "operation":"add",
  "type":"FWW",
  "value":"red",
  "name":"state1",
  "id":"abcdef"
}[

Will result in the following state:

{
  "layer:///identities/identity1": {
    "state1": {
      "adds": [
        {"ids": ["Zjf8Ac"], "value": "blue"}
      ],
      "removes": ["abcdef"]
    },
  }
}

The issuer of that operation, on receiving the updated Response Summary Part will see that the operation they issued was rejected and will update its state accordingly.

A remove operation is performed

Similarly, a remove operation can be issued (for Set and LWWN – Last Writer Wins Nullable operations only):

[{
  "operation":"remove",
  "type":"Set",
  "value":"blue",
  "name":"state1",
  "id":"Zjf8Ac"
}]

Which will add the removed ID to the removes array, and remove it from the adds array:

{
  "layer:///identities/identity1": {
    "state1": {
      "adds": [
      ],
      "removes": ["abcdef", "Zjf8Ac"]
    },
  }
}

A set operation removes a prior value

Suppose our initial state is:

{
  "layer:///identities/identity1": {
    "state1": {
      "adds": [
        {"ids": ["Zjf8Ac"], "value": "blue"}
      ],
      "removes": []
    },
  }
}

And an add operation is performed:

[{
  "operation":"add",
  "type":"LWW",
  "value":"red",
  "name":"state1",
  "id":"abczxy"
}]

The resulting state will have red as the value, and the old value’s id in removes:

{
  "layer:///identities/identity1": {
    "state1": {
      "adds": [
        {"ids": ["abczxy"], "value": "red"}
      ],
      "removes": ["Zjf8Ac"]
    },
  }
}