Administering Scripts

Aptify includes a scripting engine that executes user-defined scripts in several areas within the product. The system centralizes these scripts in a Scripts service. The standard Aptify installation supports scripting in the following entities:

• Message Parts (see Configuring Message Parts)
• Message Templates (see Creating Message Templates)
• Rule-based Process Flow Steps (see Managing Process Pipelines)
• Field Validation (see Validation Tab)
• Event Definitions (see Managing Process Pipelines)
• Price Rules (see Establishing Pricing Rules)
• Alert Types (see Creating Alert Types)

Each of these entities has an embedded link to the Scripts entity. (See Creating Embedded Objects for more information.) Also, the Code Script control appears on the form for each of these entities. This control displays the user-defined code in standard VB.NET scripting format using colors and indenting to identify keywords and other code elements, as shown below.

Note that the Database Objects service does not store SQL text in the Scripts service even though it uses the Code Script control.

This topic covers the following sub-topics:

• About the Scripting Infrastructure
• About the Code Script Control Characteristics
• About the Script Naming Conventions
• Adding Scripting to a New Entity

About the Scripting Infrastructure

Aptify includes a scripting implementation that centralizes all user-defined scripts into a central location. This functionality uses the following services:

• Script Languages: This service stores information about the supported coding languages for writing scripts in Aptify. The standard installation of Aptify supports three scripting languages:
  • VB.NET: Used by Entity Fields validation, Event Definition Filter Triggers, VBScript-based Process Flow Step Rules, and plain text Message Parts.
  • SQL: Used by SQL-based Process Flow Step rules.
  • HTML: Used by HTML Message Parts and by HTML and plain text Message Templates. 
• Script Types: This service stores information about the functional areas that support user-defined scripts and the objects that a script of a particular type can reference. The standard installation of Aptify includes four script types:
  • Messaging: This script type applies to the Message Parts and Message Templates entities.
  • Process Pipeline: This script type applies to rule-based Process Flow Steps.
  • Field: This script type applies to Entity Field validation.
  • Events: This script type applies to the Filter Trigger for Event Definitions.
  • Alerts: This script type applies to Alert notifications that can appear in the Data Control Bar.
  • Pricing Rules: This script type applies to scripts written to determine a product's price for a particular customer/member. 
• Scripts: This service stores the text of each user-defined script. It also stores a Script Name, its language, and its type. 

About the Code Script Control Characteristics

The Code Script control that appears on a form is linked to the embedded ScriptID in an entity (note that this does not apply to the Database Objects service).

When you enter a script in the control and save a record, Aptify automatically creates a Scripts record and populates the following fields:

• Script Language: The Code Script control on an entity's form is hard coded with a specific ScriptLanguageID. This selection flows down to the Scripts record.
• Script Type: The Code Script control on an entity's form is hard coded with a specific ScriptTypeID. This selection flows down to the Scripts record.
• Script Name: The system automatically generates a name for a script based on information from the record that embeds that script using the following format:
  • Message Templates: [Entity Name].[Field Name]([Record's Name].SystemID=[Record's DefaultMessageSystemID],SourceID=[Record's DefaultMessageSourceID])
    • E.g.: Message Templates.HTMLScriptID(Address Verification.SystemID=5,SourceID=2) 
  • Message Parts: [Entity Name].[Field Name]([Record's Name].CategoryID=[Record's CategoryID])
    • E.g.: Message Parts.HTMLScriptID(Two Line Address Block.CategoryID=7) 
  • All Other Script Types: [Entity Name].[Field Name]([Record's Name])
    • E.g.: Process Flow Steps.RuleTextScriptID(Show "Pending")
    • For top-level Entities, the Record's Name is the value stored in the Name field.
    • For Sub-Types, the Record's Name also includes the value of the Name fields throughout the parent hierarchy, separated by the period (.). For example, a field validation script for the Calculation Type field in the Shipment Types entity has this script name: EntityFields.ValidationScriptID(Shipment Types.CalculationType) 
• Script Text: The user-defined script is stored in this field.

The Code Script control includes a toolbar with two icons. When writing a script, you can click one of these icons to see the references and intrinsic objects that are available for use in the script and to see relevant examples (if available). The information that is displayed when you click one of these icons flows down from the appropriate Script Types record.

The icons are as follows, from left to right:

• Available Objects: Click this icon to display the intrinsic objects available for this type of script (see figure below). The objects flow down from the applicable Script Type's Available Objects tab. You can add an object to your script by placing the cursor in the desired location before clicking the Available Objects icon. Then, double-click an object or select an object and click Copy to add it to the specified location within the script. Note that double-clicking an object or clicking Copy closes the Available Objects dialog. 
  
   
• All References: Click this icon to display the list of references available for a script of this type. The references are separated into two categories: GAC Reference and Repository Reference (as shown in figure below). GAC References are objects in the Windows Global Assembly Cache. Repository References are objects in the Aptify Object Repository. The available references flow down from the applicable Script Type's Repository References and GAC References tabs.  
  
  
• Example Script: Click this icon to display any sample scripts provided for this script type. You can copy all or a portion of a sample script by placing the cursor in the desired location before clicking the Example Script icon. Then, highlight the text you want to copy to your script and click Copy. The Examples dialog closes and the text is added to the specified location within the script.
  • The examples flow from a Script Type's Languages tab. For each Script Type's Languages sub-type record, you can specify a supported scripting language and provide sample code that will appear when a user clicks the Example Script icon.
  • The Example Script icon will not appear if there is no sample code provided in a Script Type's Languages sub-type record. 

About the Script Naming Conventions

The Aptify naming convention for Scripts records is designed so that each record has a unique name. The following is an overview of the naming convention used for Scripts records:

• Message Templates: [Entity Name]. [Field Name] ([Record's Name].SystemID=[Record's DefaultMessageSystemID],SourceID=[Record's DefaultMessageSourceID])
  • E.g. Message Templates.HTMLScriptID(Address Verification.SystemID=5,SourceID=2) 
• Message Parts: [Entity Name].[Field Name]([Record's Name].CategoryID=[Record's CategoryID])
  • E.g.: Message Parts.HTMLScriptID(Two Line Address Block.CategoryID=7) 
• All Other Script Types: [Entity Name].[Field Name]([Record's Name])
  • E.g.: Process Flow Steps.RuleTextScriptID(Show "Pending")
    • For top-level Entities, the Record's Name is the value stored in the Name field.
    • For Sub-Types, the Record's Name also includes the value of the Name fields throughout the parent hierarchy, separated by the period (.). For example, a field validation script for the Calculation Type field in the Shipment Types entity has this script name: EntityFields.ValidationScriptID(Shipment Types.CalculationType). 

Adding Scripting to a New Entity

You can add scripting capabilities to a new entity by following these steps:

1. Add an embedded link to the Scripts entity's ID field in your new entity.
   • See Creating Embedded Objects for information on how to create an embedded link. 
2. Use the Visual Designer to remove the fields from the Scripts entity from your generated form.
   • See Using the Visual Designer to Modify Existing Fields for more information on deleting field parts from a form. 
3. Use the Visual Designer to add the Code Script control to your entity's form.
   • See Using the Visual Designer to Add New Fields or Controls and About the Visual Designer Code Script Control for more information. 
4. Create business logic that determines when and how to execute the script stored in your entity's records.
   • Aptify expects that a developer will complete this step; additional details are beyond the scope of this topic. Refer to the Aptify Software Development Kit (SDK) or consider taking an Aptify Developer training class for information on developer-related topics.