Skill Writing - Skill Configuration Keys

Overview

In this article, we’ll go over how to use skill configurations (skillConfig) when writing your skills in the IDE.

 

In this Article

 

What are skill configurations?

Skill configurations allow for the ability to adjust values that affect how a skill behaves without having to rewrite skill code and re-deploy the skill using the skillConfigKeys property.

 

When to use skill configuration keys

You should use skill configuration keys when you’re writing a skill containing values that may change periodically but no other aspect of how the skill functions will change. This allows skill managers the ability to maintain the values and prevent the need to write new skill code every time one of those values changes.

For example, you may want the ability to send an email to certain recipients. Rather than hard code those email addresses into the skill, you can create a skill configuration key for email address, so that the recipients can be updated at any time.

 

How to define skill configurations

You will define skill configuration properties in the skillmanifest.json file and call the key in the run.ts file in the IDE. Because you can define multiple configuration keys, whose values will be entered in the Andi® Skills Manager, use clear naming for your keys. You can also add a description for what each key is meant to do/contain by creating your key using the skillConfigKeys property. This will help ensure the skill manager knows what values to input so that the skill functions properly.

Some helpful reminders:

  • When writing the skill code, try to ensure there's no case sensitivity for text values entered
  • Try not to configure ID values, and instead, limit to text and numbers
  • Ensure there are no misspellings in the skill code if values entered on the skill page need to match that code

 

In the skillmanifest.json

You will define your key(s) as an array in the skillConfigKeys property. Keys can be entered as a string, an object, or combination of both.

  • if a skillConfigKey is entered as a string, the string will be the name of the skillConfigKey that appears in the Manager.
  • If a skillConfigKey is entered as an object, additional key values can be added to the object allowing for more robust configurations.
    • name: entered as a string, this is a required key that defines the name of the skillConfigKey and will appear in the Manager.
    • description: entered as a string, is an optional key value where you can describe how the skillConfigKey should be configured in the Manager.
    • dataType: entered as a string, this is a required key that defines how the value should be entered on the skill page and how it will be treated as part of the skill code.
      • The following Data Types can be entered:
        • text - allows you to enter a string of text
        • number - allows you to enter a number
        • date - allows you to select a date from a date picker; the date format will be ISOString
        • option- allows you to select one or more options from a list
    • options: entered as strings in an array, this key defines a list of available options to select in the Manager when the dataType is "option". To select more than one option, the multiSelect key must be defined as true.
    • multiSelect: entered as a boolean, is an optional key value that defines whether or not more than one option can be selected in the Manager. If not defined, this will default to false.

This will look like the following:

"description": "This is a description of your skill and/or keys",
"skillConfigKeys": ["thisIsAKey",
{
"name": "thisKeyIsAnObject",
"description": "You can enter an optional description of the configuration here.",
"dataType": "text"
},
{
"name": "thisIsAnOptionObject",
"dataType": "option",
"options":["optionA", "optionB", "optionC"]
},
{
"name": "thisIsAMultiSelectObject",
"description:" "This description informs what the list of options are.",
"dataType": "option",
"options":["optionA", "optionB", "optionC"],
"multiSelect": true
},
]
"locales": ["en-us"]

Using our earlier email example, the skillManifest would look like this:

"description": "This skill will send an email notification when an opportunity is closed.",
"skillConfigKeys": [
{
"name": "toEmailAddress",
"description": "Enter the recipient email address.",
"dataType":"text"
}
]

 

In previous versions of the skill kit, the skillConfigKeys property could only be entered as an array of strings. The skillConfigKeysExtended property was added to create skillConfigKeys as an object containing both a name and description. Skills containing the old skillConfigKeys and skillConfigKeysExtended schema are still supported, but newer skill versions must be updated to the latest skillConfigKey schema defined in this article.

 

In the run.ts file

You will need to call your skill key using the skillContext property. Skill code will be written as follows whether using skillConfigKeys in the skillmanifest:

skillContext.skillConfig.nameOfTheKey

Returning to our example, the run.ts file will call the key in the following manner:

// compose your email here 
let emailSubject = "An Opportunity Has Been Closed!"; 
let emailMessage =`<ul><li>Opportunity Name: ${applicationEventData.opportunityName}</li>
<li><a href="${applicationEventData.opportunityUrl}" >Click here to view the opportunity</a> </li>
</ul>`;
let toAddress = skillContext.skillConfig.toEmailAddress; let toName = skillContext.skillConfig.emailRecipientName; let fromAddress = "bank@bankname.com";
 

Once the skill has been deployed, your skill manager(s) will be able to input the appropriate value(s).

 

Was this article helpful?
0 out of 0 found this helpful