Lesson 4C - External vs. Internal References

While references can be either absolute or relative, references also allow for a file path to be used. When you want to specify a separate file in which Archy should resolve a reference, you do this with the following formatting:

    <file_path>#<yaml_path>

When you specify a file path on a reference, it is an external reference because the YAML for it comes from a file outside of the current YAML. One very important thing to note with file paths is that you should always use the '/' character for the directory separator.

Let's take a look at an example where YAML is included from externally referenced file. Here is an example setup looks like where we have a flow YAML file with a subdirectory that contains common flow logic.

archy directory
  |
  \ ---  flowDevelopment directory
           |
           + ---  mainIVRInboundCallFlow.yaml
           |
           + ---  mainInboundEmailFlow.yaml
           |
           \ ---  shared directory
                    |                                      
                    + --- commonSupportMenus.yaml      <-- a file that contains common menus
                    |                                      and / or menu choices
                    |
                    + --- commonStates.yaml            <-- common states that could be used
                    |                                      by inbound email, chat or messaging
                    |                                      flow types.
                    |
                    + --- startupTasks.yaml            <-- has different common startup tasks  
                                                           like one that gets caller info from
                                                           the caller's ANI.

The above is a hypothetical development layout using Archy but shows how YAML files can be used to compartmentalize functionality and make for useful building blocks. Using external references will let you stitch together these building blocks in flows in a reusable manner.

Let's see how the myInboundCallFlow.yaml file could reference a task in the startupTasks YAML file in the common subdirectory.

inboundCall:
  name: Default Inbound Call Flow
  defaultLanguage: en-us
  startUpRef: ./shared/startupTasks.yaml#/common/tasks/task[getCallerData]  <-- external reference
  menus:
    - menu:
        name: Main Menu
        refId: mainMenu

Notice how the startUpRef property specifies both a file path and then the path to the object in the YAML the sharedFlowLogic.yaml file. The file path and YAML path in the reference are separated by a '#' character.

In the above external reference:

            |------- file path ------| | --------- yaml path --------- |            
startUpRef: ./shared/startupTasks.yaml#/common/tasks/task[getCallerData]

Archy will first resolve the file path to:

/archy/flowDevelopment/shared/startupTasks.yaml

Remember that Archy resolves relative file references relative to the file in which they're contained. Next Archy will open the resolved file path, read in the contained YAML and if successful Archy will then go get the object referenced by the yaml path. Above we can see this is an absolute reference:

/common/tasks/task[getCallerData]

So if startupTasks.yaml looked like this:

common:
  tasks:
    - task:
        name: Get Caller Data from ANI
        refId: getCallerData
        actions:
          ... actions ...          

Next Archy will go ahead and if myInboundCallFlow.yaml doesn't have a task with the reference identifier 'getCallerData' already present, it will automatically add it to myInboundCallFlow as a reusable task. The original external reference text in the startUpRef is updated to point to the embedded task and viola, you have just used a reference to include a task from an external file.

Here's what you can think of the flow above looking like when the startUpRef external reference is resolved:

inboundCall:
  name: Default Inbound Call Flow
  defaultLanguage: en-us
  startUpRef: /inboundCall/tasks/task[getCallerData]  <-- this reference is updated
  menus:                                                  to point to the embedded task
    - menu:
        name: Main Menu
        refId: mainMenu
  tasks:                                      
    - task:                                           <-- this is the newly added task     
        name: Get Caller Data from ANI                    from the startupTasks.yaml file        
        refId: getCallerData
        actions:
          ... actions ...

Tutorial Main | Previous Lesson | Next Lesson

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