Skip to main content

YAML - Packages

YAML Packages structures are split into two parts, Conditions and Steps(Activities).

                        ── conditions: 
                       - name: 'client_filter' 
                        optMode: 'OptIn'
                        catgory: 'Testing'
                       
                       - name: 'chat'
                        option_button: 'TestGridViewPackage'
                        option_text: 'TestGridViewPackage'
                       option_category: 'testing'
                        beta_mode: 'Enabled'
                       
                       ── steps:
                       - task: inline_powershell
                        inputs:
                        script: |
                                  help Get-Command -Full | Out-GridView
                       
                       - task: chat_interaction
                        inputs:
                         text: 'Here are the views'

├── conditions: 
│   - name: 'client_filter' 
│     optMode: 'OptIn'
│     category: 'Testing'
│
│   - name: 'chat'
│     option_button: 'TestGridViewPackage'
│     option_text: 'TestGridViewPackage'
│     option_category: 'testing'
│     beta_mode: 'Enabled'
│
├── steps:
│   - task: inline_powershell
│     inputs:
│     script: |
│             help Get-Command -Full | Out-GridView
│
│   - task: chat_interaction
│     inputs:
│       text: 'Here are the views'
│

This is the most basic package YAML structure, YAML's full name is Yet Another Markup Language(like XML), it is a human-readable YAML automation language, there are other platforms or softwares are using YAML for automation as well, e.g. CHEF, ansible automation platform, Docker etc. We have defined what format to use in YAML, like conditions, steps.

YAML - Conditions

Each condition is defined as:

     - name: 'condition_name'
      property_name: 'property_value'

YAML - Activities/Steps

Each step (or activity) is defined as:

     - task: 'activity_name'
       property name: 'property value'
       inputs:
         input_name: 'input_value'

activity_name The static name of the activity - you can select this in the editor or type it in manually. You can use any of the system provided "Built-In" Activities or PowerShell Activities you create.

property_name and property_value These are additional properties which can alter the execution behaviour of the activity.

The available property_name's are:

  • executionEnvironment: Value can be one of 'PIA', 'KaseyaAgent' or 'KaseyaAgentAsUser'
  • executionEnvironmentKey: The full name of a kaseya agent (e.g. 'server.m.servers.clientname')
  • alias: An alias for the activity - must be unique for the package
  • skip: 'true' to skip the activity during exection - any other value will not skip
  • document: This value will show in the procedure documentation for the package on the client dashboard, it can be multiple lines

input_name and input_value These are inputs to the activity itself - the inputs are different for every activity. For PowerShell Activities, you define these inputs yourself. You can also use the package annotation feature to view the inputs or view them with the "Add Activity" feature of the package editor.

YAML - Input Resolution

YAML is very sensitive to syntax and formatting errors, especially when it comes to the white spaces for different levels of indentation. Normally, We use 2 spaces to denote each level of indentation, but 12 white spaces are reserved for writing good format script.

In Package Editor, the comment tag is used to insert comments in the source code. You can use comments to explain your code, which can help you when you edit the source code at a later date. This is especially useful if you have a lot of code. You can use '#' in the front of the code you want to comment out, or simply put '#' in front or middle of statement you want to comment out.

 - task: inline_powershell
  #this document content will be shown in the client dashboard, after you choosing certain package, the document will be shown as step for the package
  document: 'Checks if an existing user was found in the previous action, if an existing user was found the existing UPN and proposed new user UPN will be passed to the next activity for the user to confirm.'
  alias: existing_user 
  inputs:
    #name: =azure_generate_user_identity.name
    details: =azure_generate_user_identity.details
    script: |
            $details = [Array]$(ConvertFrom-Json $details)
            $similarAccountExists = $details.similarAccountExists
            write-host "Similar account exists: " $similarAccountExists 
            $skipExistingUserConfirmation = 'true'
            if($similarAccountExists -eq 'true'){
                $skipExistingUserConfirmation = 'false'
            }
            return @{ 
                skipExistingUserConfirmation = $skipExistingUserConfirmation; 
                existingUpn = $details.existingUpn;
                proposedUpn = $details.upn;
            }
   details: =azure_generate_user_identity.details

This is an input resolution, in fact "azure_generate_user_identity.details" is an input to this activity(task), the input needs to be resolved at runtime to retrieve an output property from another activity. This is one way we could do for input resolution, the format is =activityName.outputPropertyName

Keep in mind, if the activity has an alias, you could also reference the activity by using alias instead of using activityName which is =inline_powershell.outputPropertyName

In this example, if the activity azure_generate_user_identity has alias, which is azure_uid, we could put the input like this =azure_uid.outputPropertyName

There is a second way of doing input resolution, which is called inline input resolution.

                        - task: chat_interaction
                        inputs:
                        text: |
                        All done! A new user has been created.
                        UPN: {=userdetails.UPN}
                        Username: {=userdetails.UserName}
                        Password: {=password_form.form.password}

{=userdetails.UPN} This is an inline property.

If you are editing with the package editor, you will notice if any spaces is changed not according to what YAML's requirement, it throw an error icon almost simultaneously at the beginning to which the line belongs. If you ignore the error icon with message and insist on clicking the Save button, the button will be grey out, and down the bottom of the Package Editor, it will give you a warning "Error Saving: Cannot save while there are validation errors in your YAML syntax!". In this case, you need to refresh this page and it will direct you to the most recent version with no error syntax state.