Using Archy in Automated Environments

A common use case for Archy outside of a developer creating Architect flows is using Archy in an automated environment such as a CI/CD ( continuous integration continuous deployment ) pipeline. For example, you might have a pipeline where you want to publish flows to an organization with Archy and perform additional testing. Since we've done this at Genesys, we thought it would be helpful to have a high level discussion on what we recommend. In the end, how people want to configure automation environments is up to them, so the information below isn't some kind of requirements list but rather meant to be helpful when working in an automated environment.

To start off, when you have an environment where you spin up brand new machines to perform work, you'll obviously need to get Archy installed on the machine. One thing right off the bat is that if you use a fully qualified path to launch Archy, you don't have to worry about trying to rely on getting the Archy script / batch file in the path environment variable. Similarly, you'll probably want to use fully qualified file paths when specifying a flow YAML or options YAML file as parameter values to Archy commands. So pretty much what you're talking is unzipping Archy to an archy folder on this machine. Oh, and remember that depending on what mechanism you use to unzip the Archy zip, it could be that execute permissions on the script / batch file or Archy executable in the archyBin directory may be lost, so you'll need to either ensure that when unzipping that the permissions are maintained or add them explicitly in code after the zip file is unzipped.

Ok cool, we now have Archy installed. Yea! Inevitably the next question that comes up is "do I have to run an archy setup or archy configure on this machine so that I can run commands like archy publish to publish a flow?" The answer is no. We cover Archy commands and parameter value processing more in depth on the Archy commands page, but we recommend that you do one of the following when running commands:

1. Use an options file ( recommended ) - we often times use an options file to specify client id, secret and organization location and then when running a command like archy publish and pass in the flow YAML file to publish on a command line parameter. You can specify a value for the --file parameter in the options file too if you like. The options file is an easy way to encapsulate common values needed for commands that you want to use over and over, on different machines, etc. etc. For our pipelines at Genesys since the --file value that specifies flow YAML changes a lot between invocations of Archy, we use command line parameters for that and specify an options file that has the rest of the needed information. There is another benefit to the options file approach in that if you're using an Archy command that uses substitutions, using an options file is the only way to specify the substitution key value pairs.
2. Use command line parameters - sure, you can obviously run Archy commands and go with the tried and true method of specifying each parameter value individually as a command line parameter. It works.

Here is an example using an options file:

    
    macOS / Linux:
    ~/archy/archy publish --optionsFile ~/archy/archyHome/myOptions.yaml --file ~/archy/archyHome/myFlow.yaml
    
    Windows:
    C:\Users\myUser\archy\archy publish --optionsFile C:\Users\myUser\archy\archyHome\myOptions.yaml --file C:\Users\myUser\archy\archyHome\myFlow.yaml
    
    where the options YAML file contents are:
    
    clientId: xxx                 <-- client id and secret for the OAuth
    clientSecret: yyy                 client for the desired organization
    location: mypurecloud.com     <-- the location for the organization

The other thing to remember is that when you run Archy commands, one of the very first things Archy will write out is parameter values applicable for the command and where it got the value. An example of this output is on the Archy commands page.

If you are running multiple instances of Archy, please do note that you could encounter issues related to the creation of folders that Archy relies on for correct processing. An example of such is the debug folder in the Archy home directory. This can be easily resolved by verifying any folders exist that were in error prior to running Archy.

Running multiple instances of Archy simultaneously could also cause issues when both instances of the Archy application attempt to write to the same file at the same time. In the event you have multi-threaded code that's launching instances simultaneously, you might end up with an 'error=26, Text file busy' error.

Archy can also write out the results of a command to a JSON file that you can then utilize however you choose. You can learn more about it here.

On these pages, we will talk about how to use Archy within an automated environment using both a shell script for macOS/Linux environments and also with a batch file for Windows-based environments. The following example demonstrates how to create a flow, check in a flow (that is currently locked by another entity), and check the exit codes from both of the Archy processes. The documentation for using a bash script on macOS and Linux can be found here, and the documentation for using a batch file on Windows can be found on this page.

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