Was this Helpful?

 JavaScript policy

About | Samples | Element reference | Flow variables | Error codes  |  Schema  | Related topics

What

Configures JavaScript code to execute within the context of an API proxy flow.

Where

This policy can be attached in the following locations. See the Samples for specific attachment guidance in different situations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

The JavaScript policy below demonstrates a basic JavaScript policy that attaches a main JavaScript file called test.js. It also includes two JavaScript library files that test.js depends on: crypto.js and json2.js.

<Javascript name="ScriptPolicy1" timeLimit="200" > 
  <IncludeURL>jsc://crypto.js</IncludeURL> 
  <IncludeURL>jsc://json2.js</IncludeURL> 
  <ResourceURL>jsc://test.js</ResourceURL> 
</Javascript>

Element Reference

The element reference describes the elements and attributes of the JavaScript policy.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" 
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
</Javascript>

 

<JavaScript> attributes

<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" 
        name="JavaScript-1">
Attribute Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
timeLimit

Specifies the maximum time (in milliseconds) that the script is permitted to execute.

Note: For free trial accounts, execution time is limited to 200 ms.

N/A Required
name

The internal name of the policy. This name is referenced in Step elements to attach the policy to a Flow.

Note: Characters you can use in the name are restricted to: A-Z0-9._\-$ %. The Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

N/A Required

<DisplayName> element

A natural-language name that labels the policy in the management UI proxy editor. If omitted, the policy name attribute is used.

<DisplayName>JavaScript 1</DisplayName>
Default: Policy name attribute value.
Presence: Required
Type: String

<ResourceURL> element

This element specifies the main JavaScript file that will execute in the API flow. This file must be stored under /apiproxy/resources/jsc in the API proxy bundle, and it must implement the JavaScript object model.

<ResourceURL>jsc://my-javascript-source-file</ResourceURL>
Default: None
Presence: Required
Type: String

Example

See the Basic Example in the Samples section.

<IncludeURL>

Specifies a JavaScript library file to be loaded as dependency to the main JavaScript file specified with the ResourceURL element. Store JavaScript library files under under /apiproxy/resources/jsc in your API proxy. The scripts will be evaluated in the order in which they are listed in the policy.

    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
Default: None
Presence: Optional
Type: String

Example

See the Basic Example in the Samples section.

Usage notes

This policy allows you to implement custom behavior that is not covered by any other standard Edge policies. 

The main JavaScript file executes when the Step to which it is attached executes. A JavaScript policy contains no actual code. Instead, it references JavaScript files stored in a standard location in the API proxy bundle. 

The JavaScript resource that is referenced by the the JavaScript policy can be stored in the API configuration bundle, or it can be stored in the environment or organization. For instructions, see Resource files. You can also upload your JavaScript through the management UI proxy editor.

JavaScript resources are always stored under the /resources/jsc directory, and must also always have the .js extension. The /jsc directory indicates that this JavaScript will be compiled.

Flow Variables

This policy does not populate any variables by default; however, you can set (and get) flow variables in your JavaScript code by calling methods on the context object. A typical pattern looks like this:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

The context object is part of the Apigee Edge JavaScript Object Model. For more information, see JavaScript object model

Error codes

This policy defines the following error codes. For guidance on handling errors, see Fault handling.

The default format for error codes returned by policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The Javascript Policy type defines the following error codes:

Error Code Message
ScriptExecutionFailed Execution of {0} failed with error: {1}
ScriptExecutionFailedLineNumber Execution of {0} failed on line {2} with error: {1}
ScriptCompilationFailed Compilation of JavaScript {0} failed with error:{1}. Context {2}
NoResourceForURL Could not locate a resource with URL {0}
WrongResourceType Resource {0} is the wrong type. It is {1}: but Javascript steps use type jsc:

Schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Related topics

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)