Lesson 7 - Substitutions

Archy substitutions give you a mechanism whereby you can create flows with value placeholders and then supply values for those placeholders. A substitution is a key value pair where the key is the value you want to replace, and the value is the value to substitute in its place.

Substitution keys need to be at least one character in length and not have any leading or trailing whitespace. Substitution values must either be a string, number or boolean value.

Substitution key value pairs are submitted to Archy using the --optionsFile command line parameter.

Here is an options file that specifies three substitutions:

substitutions:
  org_greeting: Howdy
  org_name: Acme Tools
  support_queue_name: Customer Support           <-- with the assumption this queue exists in your org

Assuming we had a flow YAML file that looks like this:

inboundCall:
  name: Default Inbound Call Flow
  defaultLanguage: en-us
  startUpRef: /inboundCall/menus/menu[mainMenu]
  initialGreeting:
    tts: "{{org_greeting}}, welcome to {{org_name}}."     <-- this value has two substitutions        
  menus:                                                        make sure to quote the entire string
    - menu:  
        name: Main Menu
        audio:
          tts: You are at the Main Menu, press 8 for support or 9 to disconnect.
        refId: mainMenu        
        choices:
          - menuTransferToAcd:
              name: Transfer to Support
              dtmf: digit_8
              targetQueue:
                lit:
                  name: "{{support_queue_name}}"         <-- and here we use a substitution to supply the name of 
                                                             a queue, so make sure to quote the substitution value

If you specified the options file above, when the Archy preprocessor runs against the above flow YAML, the output will look like this:

inboundCall:
  name: Default Inbound Call Flow
  defaultLanguage: en-us
  startUpRef: /inboundCall/menus/menu[mainMenu]
  initialGreeting:
    tts: Howdy, welcome to Acme Tools.                      <-- resolved subsitutions
  menus:
    - menu:  
        name: Main Menu
        audio:
          tts: You are at the Main Menu, press 8 for support or 9 to disconnect.
        refId: mainMenu        
        choices:
          - menuTransferToAcd:
              name: Transfer to Support
              dtmf: digit_8
              targetQueue:
                lit:
                  name: Customer Support                   <-- resolved substitution

Substitutions provide a great way to supply setting values from an external file. One thing to note is that the Archy preprocessor replaces substitutions with the substitution values using a text replacement algorithm which is why you only want to use substitutions for replacing values, not entire chunks of YAML. Therefore, we recommend using substitutions to supply text for property values in YAML like we did above for the queue name and / or initial audio text to speech text. We DO NOT recommend that you attempt to try to use substitutions to embed actions, tasks, etc. etc. in to a flow. If you're looking to embed objects in to a flow, Archy has a mechanism for doing that. Use an Archy ref or refArray to do that.

• Question: Are substitution values replaced in YAML supplied from an externally referenced object in a flow?
• Answer: Yes, they will still go through the same substitution replacement algorithm. When the Archy preprocessor runs and processes a flow, it resolves out all externally referenced objects and embeds them in the flow. Once all externally referenced objects are embedded, the Archy preprocessor then performs substitution replacements.

Tutorial Main | Previous Lesson | Next Lesson

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