Lesson 6 - Using a 'refArray' object to embed an external object array

Similar to 'ref' covered in lesson 6, an object with just a 'refArray' property lets you embed an object array in place in flow YAML. You can use this to embed arrays of states, tasks, actions, menus and even menu choices.

To do this, create an object with just a 'refArray' property on it. Below we have a 'refArray' object that tells Archy to resolve the referenced array and replace it with actions contained in a 'playNums3and4' task:

inboundCall:
  name: Demo Count Call
  defaultLanguage: en-us
  startUpRef: ./tasks/task[startingTask]
  tasks:
    - task:
        name: Play 1, 2, 3, 4, 5 and disconnect
        refId: startingTask
        actions:
          - playAudio:
              name: Play 1
              audio:
                tts: "1"
          - playAudio:
              name: Play 2
              audio:
                tts: "2"
          # Reference in an array that brings in Play 3 and Play 4 play audio actions
          - refArray: ./commonLogic.yaml#/common/tasks/task[playNums3and4]/actions
          - playAudio:
              name: Play 5
              audio:
                tts: "5"
          - disconnect:
              name: bye

Assuming the commonLogic.yaml looks like this:

common:
  tasks:
    - task:
        name: Play audio "3" then "4"
        refId: playNums3and4
        actions:
          - playAudio:
              name: Play 3
              audio:
                tts: "3"
          - playAudio:
              name: Play 4
              audio:
                tts: "4"

when the Archy preprocessor resolves the 'refArray' object above, notice how the array with the actions from the common task are embedded at the same index in the array:

inboundCall:
  name: Demo Count Call
  defaultLanguage: en-us
  startUpRef: ./tasks/task[startingTask]
  tasks:
    - task:
        name: Play 1, 2, 3, 4, 5 and disconnect
        refId: startingTask
        actions:
          - playAudio:
              name: Play 1
              audio:
                tts: "1"
          - playAudio:
              name: Play 2
              audio:
                tts: "2"
          - playAudio:            # This was referenced in from the array.
              name: Play 3
              audio:
                tts: "3"
          - playAudio:
              name: Play 4        # This was also referenced in from the array.
              audio:
                tts: "4"
          - playAudio:
              name: Play 5
              audio:
                tts: "5"
            disconnect:
              name: bye

If you use 'refArray' objects in your YAML and run into issues trying to figure out why flow logic isn't looking as expected in Architect, we recommend using the Archy preprocessor to see what a flow looks like after the preprocessor runs. This will allow you to see how the 'refArray' was resolved in YAML. One thing to note is that you cannot reference an array of items in from the same file. They must always be referenced from a different file. When dealing with a common file, there is no way to reference in a shared item array.

Tutorial Main | Previous Lesson | Next Lesson

Archy - Ver. 2.33.1, generated on January 3, 2025

Lesson 6 - Using a 'refArray' object to embed an external object array

Privacy Settings