1. Andi® Support Center
  2. The Andi® Builder
  3. Powers

Field Tag Powers

Overview

A skill can be written to return one or many field tags. Use the sendFieldTag power to return a single field tag or the composeFieldTag and sendFieldTags powers to return multiple field tags. This article will cover the parameters of these powers.

 

Field Tag Powers

The composeFieldTag, sendFieldTag, and sendFieldTags powers are called via the fieldTag property of the Andi Powers on the skills context.

skillContext.powers.andi.fieldTag.composeFieldTag()
skillContext.powers.andi.fieldTag.sendFieldTag()
skillContext.powers.andi.fieldTag.sendFieldTags()

The composeFieldTag and sendFieldTag have the following shape (using sendFieldTag as an example and explained in more detail below):

return skillContext.powers.andi.fieldTag.sendFieldTag(
    type,
    key,
    displayOrder,
    text,
    fields,
    section,
    shouldIShow,
    action,
    compareHash,
    custom,
    customIcon,
),

The return from the composeFieldTag power is typically stored as an object of type FieldTagModel, which can then be used as a parameter for the sendFieldTags power.

let tag = skillContext.powers.andi.fieldTag.composeFieldTag()

If multiple field tags have been composed, one, some, or all of them can be returned as part of a single skill. To do so, an array of the field tag objects should be passed in as a parameter to the sendFieldTags power, which will typically be defined as part of a return statement. For example:

const messageOne = skillContext.powers.andi.fieldTag.composeFieldTag(
    andiSkills.FieldTagTypes.Info,
    "swap-fee-tag",
    1,
    "Click here to add 50 bps to the swap fee.",
    [],
    null,
    function() { return true; },
    null,
    null,
    null,
    null
	);

const messageTwo = skillContext.powers.andi.fieldTag.composeFieldTag(
    andiSkills.FieldTagTypes.Info,
    "swap-fee-message",
    2,
    "Contact the swaps desk at 555-555-5555 if you have any questions about today's indicative pricing.",
    [],
    null,
    function() { return true; },
    null,
    null,
    null,
    null
);

return skillContext.powers.andi.fieldTag.sendFieldTags([messageOne, messageTwo]);

 

Field Tag Power Parameters

type

The type parameter, which is a required parameter, is where you will indicate the field tag type, which will determine the color of the field tag displayed in the application. Click here for definitions and colors of the available field tag types. You will indicate the type using

andiSkills.FieldTagTypes.typeNameSelectionHere

Available options that will display when using this power are:

  • Info
  • Warning
  • ValueForTarget

For help tags, use the chat powers.

As part of the basic skill code shape, this will look like:

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,

key

The key parameter, which is a required parameter entered as a string, is a unique value used to identify the field tag when it runs in the application.

As part of the basic skill code shape, this will look like:

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",

displayOrder

The displayOrder parameter, which is a required parameter entered as a number, is where the sorting order will be indicated for the field tag and applies to that particular field tag type. For example, if '2' is entered for a field tag type of 'Warning', then it will display second amongst all Warning field tags in the Andi® window. Field tags with a display order less than 100 will display, before built in PrecisionLener field tags of the same type. For field tags that display in the Andi window, in the event that two field tag skills of the same displayOrder and type are deployed and made available for everyone, the field tag that appears first will be based on when the skill runs.

As part of the skill code, this will look like:

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,

text

The text parameter, which is a required parameter entered as a string or predefined variable (recommended and further recommended to define the variable using skill configurations), is where you will enter the message that will display in the field tag. This parameter cannot be left blank.

As part of the basic skill code shape, this will look like:

//Option 1 - text entered as a string

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,
    "this is the message that will display",


//Option 2 - text entered as a variable

let message = "this is the message that will display"

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,
    message,

fields

The fields parameter, which is a required parameter entered as a string in an array, is where you can identify the field that you'd like the field tag to display. When tagged to a field, the field tag displays in the field tag bubble for that field, along with any other field tags tagged to that field. See Opportunity Screen Field Tag Placement for a list of available fields.

  • If only displaying the field tag in the Andi® window, you can enter an empty array '[]' as the parameter. This tag will be referred to as a Summary tag.
    • Additionally, summary tags take into consideration the context of the event to determine the relevancy of displaying the tag in the Andi® window.
      • For instance, the loan tab and the deposits tab represent two different view contexts in the Opportunity screen. If the summary tag shows for a depositChangeEvent, it will only show in the Andi® window on the Deposits tab and not the Loan tab(s) because a deposit event is most relevant to the Deposits tab.
    • To show a summary tag regardless of the viewed context, add "deposits" and/or "others" to the fields array.
  • If displaying in another field, then the field name(s) will need to be specified. The field tag will also display in the Andi® window.
  • To prevent display in the Andi® window when displaying the tag in another field, use the field name 'disableforandibutton'.

As part of the basic skill code shape, this will look like:

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,
    "this is the message that will display",
    ["amount"],

section

The section parameter, which is a required parameter and entered as an object or defined as 'null', allows you to create custom summary headers that your tags can be categorized under.

In general, tags are categorized and assigned to the standard sections based on the FieldTagType and then the sections are displayed in the field tag bubble and Andi® Window based on the priority of those types. After ordering for priority, all sections act as the most important field tag inside of themselves with regards to display order, and the lowest priority is at the top. Those fieldTagTypes and their standard section, in ranking order, are as follows:

  • There appears to be an error - for ValueForTarget types
  • Here are some concerns - for Warning types
  • Here are ways to reach the target - for standard PrecisionLender Solver Skills
  • Here are things to consider - for Info types
  • I found these help resources - for Help types

Custom summary headers allow you to add additional sections to categorize your tags. This can make it easier to distinguish your skills from the standard PrecisionLender skills.

To create a summary header, you'll define the FieldTagSection object with the following properties

{headerText: string, name: string}

where

  • headerText is a required property and is the summary text that will display in the field tag bubble and Andi® window, and
  • name is an optional property that you can use to categorize your headers. This will not display in the field tag bubble or Andi® Window.

You can add the same object parameters to multiple tags to group them under the same header. However, you will need to make sure the headerText is entered the same for each one.

When adding a custom summary header, the order of the section in the field tag bubble and Andi® Window will be determined by the highest ranking fieldTagTypes of the tags assigned to the section. If multiple sections contain the same fieldTagType, then the sections will be positioned based on the headerText in alphabetical order. Some examples:

  • A custom section with two summary tags, a Warning fieldTagType and an Info fieldTagType, will display after sections containing a ValueForTarget fieldTagType but before the "Here are some concerns" section if the headerText starts with a letter 'A' to letters 'Herd' and after that section if it starts with letters 'Herf' to letter 'Z'.
  • A custom section with an Info fieldTagType only, will display after all sections containing ValueForTarget and Warning fieldtagTypes but before any section containing Help fieldTagTypes.

If not creating a summary header, then you'll define section as 'null' and the field tag type parameter will determine the section the field tag message displays in, in the Andi® Window.

As part of the basic skill code shape, this will look like:

//with a custom summary header
return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,
    "this is the message that will display",
    ["amount"],
    {
        headerText: "Pricing Considerations for Loans of this Size", 
        name: "Pricing Considerations"
    },

//without a custom summary header 
return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3, 
    "this is the message that will display",
    ["amount"],
    null,

shouldIShow

The shouldIShow parameter, which is a required parameter, is a client side function that considers api, model, comparehash, and custom parameter logic where defined to determine if the field tag should be displayed. This is most useful to help determine whether a field tag is still relevant to display as events continue to occur.

  • api: this uses pageApi, not external api, methods that can be used for your field tag. On 'get' and 'is' (read-only) pageApi functions can be used inside the shouldIShow. Page setters cannot be used for this function and will be used inside the action function.
  • model: this uses the client-side oppportunityModel to access data that you can use to help determine whether or not your field tag should show.
  • compareHash
  • custom

In the 'Field Tag' Skill Template, the shouldIShow is defined using data from the model parameter so that the field tag only shows if the number of newly priced deposits is more than 0. This means that if a deposit is added, and then removed, the field tag message should no longer display.

function(api, model, comparehash, custom){

    var eventData = model.applicationEventData; 

    // make sure that anytime deposits are removed - it stops showing this message
    var shouldIShow = eventData.engineModel.depositAccounts &&  eventData.engineModel.depositAccounts.length > 0;

    return shouldIShow;
},

As another example, in this shouldIShow function, both the model and custom parameters are used to determine when a field tag designed to display an approval workflow message, should show. The custom components of this function are in the custom section below.

function(api, model, comparehash, custom){
    //return true;
    var eventData = model.applicationEventData; 
    var shouldIShow = false;
    var currentLoan;
    var hasLoan = eventData.engineModel.commercialLoanAccounts &&  eventData.engineModel.commercialLoanAccounts.length > 0;

    if(hasLoan){                
        currentLoan = eventData.engineModel.commercialLoanAccounts.find(function(loan) {
        return  custom.productFamilyIds.indexOf(loan.product.productFamilyId) > -1;
        });
    }

    if(currentLoan && currentLoan.amount > 10000000 && currentLoan.amount < 25000000) 
        shouldIShow = true;

    return shouldIShow;
},

If the field tag does not need to define any parameters as part of the shouldIShow, then the function should return true so that the field tag shows.

//option 1 -- return true with a shouldIShow variable
	
function(api, model, comparehash, custom) {
    var shouldIShow = true;
		
    return shouldIShow
		
},
	
//option 2 -- return true as a boolean
	
function(api, model, comparehash, custom){
    return true;
},

As part of the basic skill code shape, this will look like:

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,
    "this is the message that will display",
    ["amount"],
    null,
    function(api, model, comparehash, custom) {
        var eventData = model.applicationEventData;
        var shouldIShow = false;
        var currentLoan;
        var hasLoan = eventData.engineModel.commercialLoanAccounts &&
          eventData.engineModel.commercialLoanAccounts.length > 0; 

        if(hasLoan){
            currentLoan = eventData.engineModel.commercialLoanAccounts.find( function(loan) {
            return custom.productFamilyIds.indexOf(loan.product.productFamilyId) > -1;
            });
        }

        if(currentLoan && currentLoan.amount > 10000000 && currentLoan.amount < 25000000)
            shouldIShow = true;

        return shouldIShow;	
    },

action

The action parameter is an optional client side function that can make your field tag more powerful and valuable. You can use api, model, and custom parameter logic to generate a link within the field tag, that when clicked, performs the defined action.

  • api: this uses pageApi, not external api, methods to make your field tag actionable.
  • model: this uses the client-side oppportunityModel to access data that you can use to help determine whether or not your field tag should show.
  • custom

This action function uses the pageApi openEmail method that will generate an approval email request to the listed recipients when the field tag is clicked. The custom component of this action function, custom.oppUrl, is explained in the custom section below.

function (api, model, custom) {
    api.page.openEmail("andi@andi.com", "Loan requires approval of Regional EVP", custom.oppUrl, "andi2@andi.com");
},

If no action parameter is being defined, enter 'null'.

As part of the basic skill code shape, this will look like:

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,
    "this is the message that will display",
    [],
    null,
    function(api, model, comparehash, custom) {
        var eventData = model.applicationEventData;
        var shouldIShow = false;
        var currentLoan;
        var hasLoan = eventData.engineModel.commercialLoanAccounts &&
          eventData.engineModel.commercialLoanAccounts.length > 0; 

        if(hasLoan){
            currentLoan = eventData.engineModel.commercialLoanAccounts.find( function(loan) {
            return custom.productFamilyIds.indexOf(loan.product.productFamilyId) > -1;
            });
        }

        if(currentLoan && currentLoan.amount > 10000000 && currentLoan.amount < 25000000)
            shouldIShow = true;

        return shouldIShow;	
    },
    function (api, model, custom) {
        api.page.openEmail("andi@andi.com", "Loan requires approval of Regional EVP", custom.oppUrl, "andi2@andi.com");
    },

compareHash

compareHash is an optional parameter, that if defined, sends a hash from the server side that can be used by the client side for a shouldIShow and/or action function. Often times, the client side actions occur more quickly than server side actions, and the hash will help keep the skill from running so as not to provide stale information. The shape defined here will be made available for the custom variable in shouldIShow and action.

Due to the complexity of this parameter, please contact Andi® Support if you need assistance with defining this in your skill.

If no compareHash parameter is being defined, enter 'null'.

As part of the basic skill code shape, this will look like:

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,
    "this is the message that will display",
    [],
    null,
    function(api, model, comparehash, custom) {
        var eventData = model.applicationEventData;
        var shouldIShow = false;
        var currentLoan;
        var hasLoan = eventData.engineModel.commercialLoanAccounts &&
          eventData.engineModel.commercialLoanAccounts.length > 0; 

        if(hasLoan){
            currentLoan = eventData.engineModel.commercialLoanAccounts.find( function(loan) {
            return custom.productFamilyIds.indexOf(loan.product.productFamilyId) > -1;
            });
        }

        if(currentLoan && currentLoan.amount > 10000000 && currentLoan.amount < 25000000)
            shouldIShow = true;

        return shouldIShow;	
    },
    function (api, model, custom) {
        api.page.openEmail("andi@andi.com", "Loan requires approval of Regional EVP", custom.oppUrl, "andi2@andi.com");
    },
    null, //no comparehash

custom

custom is an optional parameter, that if defined, allows an object to be sent from server side to client side for a shouldIShow and/or action function. The shape defined here will be made available for the custom variable in shouldIShow and action.

{objectName: objectParameter, objectName2: objectParameter}

The shouldIShow and action function examples above use custom objects for productFamilyIds and oppUrl.

{ productFamilyIds: productFamilyIds, oppUrl:oppUrl }

The custom object for each of those was defined using variables of the same name, allowing the code inside the custom object to remain clean and easy to navigate.

let eventData = skillContext.powers.precisionLender.opportunity.getOpportunityChangeEventData();
let opportunityData = eventData as andiExternal.PrecisionLenderOpportunityChangeEvent.OpportunityChangeEvent; 
let productFamilyIds = ["8548c4cd-95eb-4f97-8e54-060f92095e67","c4204997-1613-4182-a580-bb8a45327842"];
let oppUrl = "https://application.precisionlender.com/price/opportunity/" + opportunityData.opportunityDetails.id;

If no custom object is being defined, enter 'null'.

As part of the basic skill code shape, this will look like:

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,
    "this is the message that will display",
    [],
    null,
    function(api, model, comparehash, custom) {
        var eventData = model.applicationEventData;
        var shouldIShow = false;
        var currentLoan;
        var hasLoan = eventData.engineModel.commercialLoanAccounts &&
          eventData.engineModel.commercialLoanAccounts.length > 0; 

        if(hasLoan){
            currentLoan = eventData.engineModel.commercialLoanAccounts.find( function(loan) {
            return custom.productFamilyIds.indexOf(loan.product.productFamilyId) > -1;
            });
        }

        if(currentLoan && currentLoan.amount > 10000000 && currentLoan.amount < 25000000)
            shouldIShow = true;

        return shouldIShow;	
    },
    function (api, model, custom) {
        api.page.openEmail("andi@andi.com", "Loan requires approval of Regional EVP", custom.oppUrl, "andi2@andi.com");
    },
    null, //no comparehash
    { productFamilyIds: productFamilyIds, oppUrl:oppUrl },

customIcon

customIcon is an optional parameter, that if defined, allows you to display an icon that represents your organization next to the field tag message.

  • If an icon has not been uploaded to the Andi® Skill Manager for your organization or to upload an icon representing a different organziation, then you will need to provide the icon url for an svg file.
  • If an icon has been uploaded to the Andi® Skill Manager for your organization (for which the icon will appear by default) or you do not want to include an icon (if one has not been uploaded), then you can choose to either enter a value of 'null' or skip entry of any parameter.

As part of the basic skill code shape, this will look like:

return skillContext.powers.andi.fieldTag.sendFieldTag(
    andiSkills.FieldTagTypes.Info,
    "this-is-a-key",
    3,
    "this is the message that will display",
    [],
    null,
    function(api, model, comparehash, custom) {
        var eventData = model.applicationEventData;
        var shouldIShow = false;
        var currentLoan;
        var hasLoan = eventData.engineModel.commercialLoanAccounts &&
          eventData.engineModel.commercialLoanAccounts.length > 0; 

        if(hasLoan){
            currentLoan = eventData.engineModel.commercialLoanAccounts.find( function(loan) {
            return custom.productFamilyIds.indexOf(loan.product.productFamilyId) > -1;
            });
        }

        if(currentLoan && currentLoan.amount > 10000000 && currentLoan.amount < 25000000)
            shouldIShow = true;

        return shouldIShow;	
    },
    function (api, model, custom) {
        api.page.openEmail("andi@andi.com", "Loan requires approval of Regional EVP", custom.oppUrl, "andi2@andi.com");
    },
    null, //no comparehash
    { productFamilyIds: productFamilyIds, oppUrl:oppUrl },
    //no customIcon
)

 

For an example of a skill using the sendFieldTag power, see 'Field Tag' Skill Template.

Articles in this section

See more
Was this article helpful?
2 out of 2 found this helpful