Getting Started with Scripts
Learn about the script creation process, using a script activity in a process, documentation, and management tools.
Table of Contents
- Script Contexts
- Add Script
- Reference Script
- Script Activity
- Pre-Defined Script Objects
- Sequence of Script Processing
- Policy Manager Scripting API
- Process Reference
- Script Management Tools
- What's Next?
Akana Policy Manager provides a scripts interface that is available in the Scripts folder of each Organization. It allows you to define a series of utility scripts for performing common tasks. You can then import and reference scripts:
- In a Process definition using the Script Activity
- In a QoS or Operational Script Policy
Let's take a quick walkthrough of the script creation options and tools available to get you started.
There are several ways that you can configure your script definitions:
- You can define a script object in the Scripts section, using the Add Script function. This is useful for building a library of scripts you can reuse in your Process or Script Policy definitions.
- You can create a process, add a Script Activity, and then import an existing script.
- If there is a portion of a pre-defined script object that you want to use in your local script, you can import the script object and then reference it in the imported script.
- You can use scripts in workflows. See Using Scripts in Workflows.
You add a script using the Add Script function on the Scripts Summary page.
The steps are:
- Add your script content.
The example below shows adding the first script, so there are no existing scripts in the Available Scripts section. This section represents scripts that are available to be imported. In this example, we are adding a script named Sample Script.
After you save the script and are creating an additional script, all existing scripts are displayed in the Available Scripts section. In the example below, Sample Script is now available. This means that it can be reused by importing it into a new script definition.
Now that you've added a script, let's see how to reference a script. See Reference Script below.
After you add your set of utility scripts, in your virtual service operation process definition, you can:
- Add a Script Activity
- Import a pre-defined script
- Add a script reference for the function you want to perform
For example, let's say you have a requirement to validate some data as part of your process. To do this, you created a reusable script, TestScript, that includes a function for validating data (validateData). In your process definition, import TestScript and reference the function in the script source as shown below.
The Script Details Editor is organized into two separate areas, Imports and Source. In the Source tab, you can:
- Choose from a list of supported script languages.
- Write or paste the script, in the large source code editor text area.
You can save common functions, that you might want to re-use in your scripts, as Script objects. In the Policy Manager Workbench, for each organization, there is a Scripts section. To add a re-usable script for the organization, go to the Scripts section and click Add Script.
Within the Script activity, to use a common function, you must import the Script object that defines the function. Scripts are defined for import in the Imports area. Available scripts are listed in the Available Scripts tree, as shown below.
You can move any number of scripts from Available Scripts to the Imported Scripts list box. Only scripts in the specified scripting language type are displayed.
The script does not return a value.
In the illustration above, the json2 script from the Registry/Scripts folder is imported. Once you import a script, you can use any functions that are defined in that script, within the Script Activity source code.
Pre-Defined Script Objects
The platform includes some pre-defined objects that you can use in your scripts.
From the script workspace, to access the list of pre-defined script objects, type CTRL+Space, and then choose from the list below. Typing a period (.) after the script object name, followed by CTRL+Space, allows you to select from the available methods for the object.
The pre-defined script objects are shown below. These objects are available for all three supported scripting languages.
- result (2018.0.0 and later): Allows the script to indicate its status to the policy framework. The result object has two methods:
- result.isSuccess(): Returns a Boolean indicating whether or not message processing should proceed.
- result.setSuccess(Boolean status): Accepts a Boolean value indicating whether or not script execution was successful and message processing should proceed as normal.
- recorder: Provides an interface for recording content in the Policy Manager usage log pages.
- auditLog: Provides logging functions to the process audit log. If auditing is enabled for the virtual service operation that is invoking the process statements logged using this variable, log information will be inserted into the audited message log for the operation’s execution. In Policy Manager, you can find this information on the Monitoring tab for the service, in the Logs sub-tab.
- messageContext: Provides information about the platform's message handler framework's processing of a message. From the context you can get information such as the message being processed, the role of the message in a message exchange (IN, OUT, FAULT), and properties that can be changed and read by the chain of handlers that process the message.
- alerter: Provides an interface for generating alerts that are displayed on the Policy Manager alert pages.
- msgFactory: Provides functions for creating message variables. A message variable cannot simply be assigned content such as a simple string or int variable. It must be initialized using one of the functions in the msgFactory.
- processContext: Provides functions for retrieving and changing information about the currently running process, such as the variables defined in the process and one or more authenticated subjects of the process.
- systemLog: Provides logging functions to the container’s log. The statements logged with this interface are mixed with the other system log statements.
- msgrService: Provides a messaging bus for exchanging messages with web services. The MessengerService provides access to an ExchangeFactory for creating Exchanges and a Messenger for executing them.
For more information, refer to the Scripting API documentation; see Policy Manager Scripting API below.
Sequence of Script Processing
The script associated with an Operational Script policy is executed before the script associated with a process. For this reason, some properties in messages might be missing.
Policy Manager Scripting API
The Policy Manager Scripting API provides a series of interfaces and classes that you can use to build process-related scripts. The API includes lots of use cases and sample code you can experiment with and use as a baseline when building your own scripts. You can access the scripting API documentation in the following locations:
- In the docs\scriptDocs folder of the Akana Platform folder.
- On the Akana docs site: Policy Manager Scripting API
Another essential resource you will need when working with Processes and Scripts is the Process Reference for Policy Manager document. Here you will learn all the fundamentals about creating a process, using the process editors, and configuring activities.
Script Management Tools
For an overview of all the available tools for managing Script definitions, see Managing Scripts.
Now that you've familiarized yourself with high-level information about building scripts, and know what reference materials and tools are available, you can start building your script library and begin to automate your process definitions and QoS Script Policies.