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 Methods
- 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 functions 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.
The platform includes some pre-defined methods that you can use in your scripts.
From the script workspace, to access the list of pre-defined methods, type CTRL+Space, choose from the list below, and then type a period (.) after the method.
For Jython and BeanShell Engine, the pre-defined methods are shown below.
- result: Stops the processing for the message exchange, so the proxy endpoint is not called and the response is HTTP 200 with empty content. (2018.0.0 and later)
- 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 proprties in messages might be missing.
In the context of an Operational Script policy, the messageContext method is available.
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 (Policy Manager 8.x). 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.