Getting Started with Scripts

Learn about the script creation process, using a script activity in a process, documentation, and management tools.

Table of Contents

Overview

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.

Script Contexts

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.
  • You can create a QoS or Operational Script Policy and then, from within that context, define a new script or import an existing script. For example, choose Policies > Operational Policies > Add Policy and choose either Private Operational Script Policy or Public Operational Script Policy. Once you've defined the policy, you can add the script, in JavaScript, Jython, or BeanShell Engine. For more information, see Using the Public and Private Operational Script Policies.
  • 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.

Add Script

You add a script using the Add Script function on the Scripts Summary page.

Scripts Summary page

The steps are:

  1. Select the language you will be writing your script in (JavaScript, Jython, or BeanShell engine).
  2. Add your script content.
  3. Save.

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.

scripts available to be imported

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.

sample script is now available

Now that you've added a script, let's see how to reference a script. See Reference Script below.

Reference Script

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.

referencing a script function

Script Activity

The Script Activity provides the ability to execute a script as part of a process. The script is executed at the point in the process at which the activity is connected. The script can be written in JavaScript, Jython, or BeanShell.

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.

Script Activity Source 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.

Script Activity Imports Area

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.

Default methods for scripts

Default methods for scripts, detail

The pre-defined script objects are shown below. These objects are available for all three supported scripting languages.

  • result: 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 JavaScript, supported JavaScript keywords are included on the list, as shown below. Information on these is generally available in JavaScript reference works.

Default methods for JavaScript

Supported JavaScript keywords include:

  • break
  • case
  • catch
  • continue
  • debugger
  • default
  • delete
  • do
  • else
  • false
  • finally
  • for
  • function
  • if
  • in
  • instanceof
  • new
  • null
  • return
  • switch
  • throw
  • true
  • try
  • typeof
  • var
  • void
  • while
  • with

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.

In the context of an Operational Script policy, the messageContext and result script objects are available.

In the context of a process, the processContext and recorder script objects are available.

Other available objects listed in Pre-Defined Script Objects above are available in both contexts: auditLog, systemLog, alerter, msgFactory, and msgrService.

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:

Process Reference

Another essential resource you will need when working with Processes and Scripts is the Process Reference 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.

script management tools

What's Next?

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.