Writing a Snippet Argument

A Snippet Argument provides the execution plan to the Snippet Framework and enables low-code/no-code collections.

Before writing a Snippet Argument, you must first understand how to collect the required data and ensure that step(s) exist for the required tasks. If a step does not exist, determine if you can chain steps together to get the required result. After you know what steps to use, then you can write the Snippet Argument for the given Syntax.

The most basic form of writing a Snippet Argument is through the low_code Syntax which we will use for the examples.

Example: Collecting device names from an AIO SL1 System

For this example, we will collect device names from a SL1 system. The required operations for collecting the data will be as follows:

Perform a HTTP request to /api/device on localhost (due to this being an AIO we can use localhost instead of an ip address or hostname)

Interpret the text response as JSON
Convert the results to a python dictionary with the following structure:
{
    "device_uri": "device_name"
}

After determining how to collect the data, we then need to determine if our tasks have existing steps around them. For this scenario, we will use the following steps:

Steps for collection
Operation	Step
Perform a HTTP request	http
Convert response from JSON	json
Convert the result to a dictionary	jmespath

Now that we know what steps to use, we will need to determine what arguments, if any, need to be supplied to the step.

Determining Step Parameters

http

After reviewing the available parameters for http and determining that we will be specifying the entire URL, we only need to provide the step with the url parameter. The username / password will automatically be consumed from the credential.

http:
  url: http://localhost:80/api/device

json

After reviewing the available parameters for json, we notice that no parameters are required for this step.

json

jmespath

After reviewing the available parameters for jmespath, we determine that we will need to use index and value to construct our dictionary.

Note

This section is not a deep-dive into jmespath. For additional documentation around jmespath, refer to the official documentation.

jmespath:
  index: true
  value: "values(@)|[].{_index: URI, _value: description}"

Creating the Snippet Argument

Now that we have the steps and their parameters to perform the collection, we need to write our final Snippet Argument using the low_code version 2 Syntax. We will add all our steps under the steps section, which takes a list of values.

low_code:
  version: 2
  steps:
    - http:
        url: http://localhost:80/api/device
    - json
    - jmespath:
        index: true
        value: "values(@)|[].{_index: URI, _value: description}"

Example: Collecting aligned organization for a device

For this example, we will collect the aligned organization for a given device. Since part of the URI is dynamic, in this case the device id, we will utilize substitution that will automatically substitute context-aware information into the Snippet Argument. The required operations for collecting the data will be as follows:

Perform a HTTP request to /api/device/<device_id> on localhost (due to this being an AIO we can use localhost instead of an ip address or hostname)

Interpret the text response as JSON

Select a value from the dictionary

After determining how to collect the data, we then need to determine if our tasks have existing steps around them. For this scenario, we will use the following steps:

Steps for collection
Operation	Step
Perform a HTTP request	http
Convert response from JSON	json
Convert the result to a dictionary	jmespath

Now that we know what steps to use, we will need to determine what arguments, if any, need to be supplied to the step.

Determining Step Parameters

http

After reviewing the available parameters for http and determining that we will be specifying the entire URL, we only need to provide the step with the url parameter. The username / password will automatically be consumed from the credential. Since we need context-aware information, device id, we will use substitution to get this information. After referring to the available substitution parameters, we determine that we will need to use ${silo_did} to construct the url http://localhost:80/api/device/1.

http:
  url: http://localhost:80/api/device/${silo_did}

json

After reviewing the available parameters for json, we notice that no parameters are required for this step.

json

jmespath

After reviewing the available parameters for jmespath, we determine that we will need to use value to extract our data.

Note

This section is not a deep-dive into jmespath. For additional documentation around jmespath, refer to the official documentation.

jmespath:
  value: organization

Creating the Snippet Argument

Now that we have the steps and their parameters to perform the collection, we need to write our final Snippet Argument using the low_code version 2 Syntax. We will add all our steps under the steps section, which takes a list of values.

low_code:
  version: 2
  steps:
    - http:
        url: http://localhost:80/api/device/${silo_did}
    - json
    - jmespath:
        value: organization

Example: Collection with Custom Substitution

For this example, we will collect the aligned organization for a given device. Since part of the URI is dynamic, in this case the device id, we will utilize substitution that will automatically substitute context-aware information into the Snippet Argument. The required operations for collecting the data will be as follows:

Perform a HTTP request to /api/device/<device_id> on localhost (due to this being an AIO we can use localhost instead of an ip address or hostname)

Interpret the text response as JSON

Select a value from the dictionary

After determining how to collect the data, we then need to determine if our tasks have existing steps around them. For this scenario, we will use the following steps:

Steps for collection
Operation	Step
Perform a HTTP request	http
Convert response from JSON	json
Convert the result to a dictionary	jmespath

Now that we know what steps to use, we will need to determine what arguments, if any, need to be supplied to the step.

Writing a custom substitution function

For this example, we want our custom substitution function to return /api/device/<device_id>. After referring to the Custom Substitution document, we can write a function that returns our string.

def generate_uri(silo_did):
    return "/api/device/{}".format(silo_did)

We would need to update the default snippet with our new function too.

from silo.apps.errors import error_manager
with error_manager(self):

    from silo.low_code import *
    from silo.apps.collection import create_collections, save_collections

    # =====================================
    # =========== User Editable ===========
    # =====================================
   def generate_uri(silo_did):
       return "/api/device/{}".format(silo_did)

    # List any custom substitutions that need to occur within the snippet arguments
    custom_substitution = {"generate_uri": generate_uri}
    # =====================================
    # ========= End User Editable =========
    # =====================================


    collections = create_collections(self)
    snippet_framework(collections, custom_substitution, snippet_id, app=self)
    save_collections(collections, self)

Determining Step Parameters

http

After reviewing the available parameters for http and determining that we will be specifying the entire URL, we only need to provide the step with the url parameter. The username / password will automatically be consumed from the credential. Since we plan on utilizing the custom substitution function to generate the uri, we will reference that substitution within the url parameter.

http:
  url: http://localhost:80/${generate_uri}

json

After reviewing the available parameters for json, we notice that no parameters are required for this step.

json

jmespath

After reviewing the available parameters for jmespath, we determine that we will need to use value to extract our data.

Note

This section is not a deep-dive into jmespath. For additional documentation around jmespath, refer to the official documentation.

jmespath:
  value: organization

Creating the Snippet Argument

Now that we have the steps and their parameters to perform the collection, we need to write our final Snippet Argument using the low_code version 2 Syntax. We will add all our steps under the steps section, which takes a list of values.

low_code:
  version: 2
  steps:
    - http:
        url: http://localhost:80/${generate_uri}
    - json
    - jmespath:
        value: organization