The Custom Action Template is a set of scripts to make it easier for end-users of Canopy Manage to run custom scripts on a local or virtual machine as Custom Actions in Canopy. These scripts are available in a zip: Canopy Tools - Custom Action Template.



Requirements

The Custom Action Template is written in Python for Python 3.6 or later. 64 Bit is recommended as it provides the best compatibility with calling Powershell scripts.

Contents

  • Custom_Action_Template.py - The actual template which calls your own scripts and posts back to Canopy
  • sample_config_queue.json - a sample configuration file configured to use Azure Queues (Topics coming soon)
  • sample.py and sample.ps1 - sample Python and Powershell scripts that simply output any parameters send to them so that the Template can send this back to Canopy. You can use this to test your set up and configuration. They both do the same thing so use either depending on your preferred scripting host.
  • requirements.txt - a listing of required Python modules for installation with pip

Installation

The Custom Action Template comes as a Zip file, so you need to simply unzip the files to a location of your choice somewhere on the local/virtual machine.


We recommend keeping the Custom Action Template within the same file tree as the scripts you wish to run, however it can be saved anywhere on the machine.


The Custom Action Template requires several additional Python modules to run - these can be found in the requirements.txt document.

To install these azure elements, simply open a Command Line of your choice in the Custom Action Template folder and run the following command (Note: this needs to be run inside the same folder as requirements.txt): 



pip install -r requirements.txt


Config.json

We have provided a sample config file for Azure Queues though your actual config file will need to be called config.json and saved alongside the custom_action_template.py script. Alternatively you can save your config file somewhere and provide the path to it (for example your config was one level above the Canopy Custom Action Template:


python custom_action_template.py -c ../config.json


Once you have installed the additional Azure elements, you will need to update the config.json file to tell the Custom Action Template which Service Bus queue to listen to - 

This is a block of text, formatted correctly. Insert me into the document to being a new block of formatted text.

In our example above - 


connectorType - Since we are using an Azure Service Bus queue, the type is "Queue"

queue - This is the name of the queue we are connecting to, in this example it is samplequeue

queueConnectionString - This is the Primary Connection string for the Shared Access Policy for the Service Bus. In this case we have a "ListenOnly" policy which gives Listen Permissions.

executables - this is where the location of the script/s to run should be noted.

- Notes: 

    - The value is a child JSON object in the format:

{

"command": "powershell", 

"script": "C:/projects/automation/custom_action_templates/sample.ps1", 

"args": "-d"

},

- The command object is generally the scripting host - powershell, python, ruby, etc. But technically you can call a native executable. 

- The script object is generally the script you want to run, but in the case of calling executables directly this would be the first parameter passed to that executable. 

- The args object is optional and can be used to pass a single parameter to the script independently of the Custom Action configuration in Canopy. Dynamic parameters (that you need to change with each run) are set up as Custom Action Field Schemes in Canopy Manage. The Custom Action Template will send dynamic parameters to your script in the format: "-paramName paramValue". 


- The key you use in the key-value pair will be the same key assigned to the Custom Action in Canopy Manage.

- You can have multiple scripts listed and running from the same Queue. Simply add additional key-value pairs to the executables in the same style, making sure to separate with a comma (,)

- The file path for each script must be the full file path for the Custom Action Template to find and run the script.

- File Paths must use forward slash (/), not back slash (\), as back slash is used to escape characters and will cause an error.

- We recommend not having spaces in your file path, however if you must, please add an additional set of quotation marks to the file path, using  back slash (\) to escape the characters. For Example:

"\"C:/Users/user/Documents/Scripts/sample script.ps1\""



Once this is complete, select and run the Custom_Action_Template.py python file. This file will now listen to the queue listed in config.json and run the scripts sent to it. 


Note: This file must be running for the scripts to be actioned.


See our article Set Up - Custom Actions for further steps on creating a Custom Action in Canopy Manage.