You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs). info ![](https://docs.apigee.com/static/api-platform/images/icon_policy_javaScript.jpg) ### What This policy lets you add custom JavaScript code that executes within the context of an API proxy flow. In your custom JavaScript code, you can use the objects, methods, and properties of the Apigee Edge [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model). The object model lets you get, set, and remove variables in the proxy flow context. You can also use basic cryptographic functions that are provided with the object model. ### About There are many use cases for the JavaScript policy. For example, you can get and set flow variables, execute custom logic and perform fault handling, extract data from requests or responses, dynamically edit the backend target URL, and much more. This policy allows you to implement custom behavior that is not covered by any other standard Edge policies. In fact, you can use a JavaScript policy to achieve many of the same behaviors implemented by other policies, like AssignMessage and ExtractVariable. One use case we don't recommend for the JavaScript policy is logging. The [Message Logging policy](https://docs.apigee.com/api-platform/reference/policies/message-logging-policy) is much better suited for logging to third-party logging platforms such as Splunk, Sumo, and Loggly, and you improve API proxy performance by executing the Message Logging policy in the PostClientFlow, which executes after the response has been sent back to the client. The JavaScript policy lets you specify a JavaScript source file to execute or you can include JavaScript code directly in the policy's configuration with the `` element. Either way, the JavaScript code executes when the step to which the policy is attached executes. For the source file option, the source code is always stored in a standard location within the proxy bundle: `apiproxy/resources/jsc`. Or, you can also store the source code in a resource file at the environment or organization level. For instructions, see [Resource files](https://docs.apigee.com/api-platform/develop/resource-files). You can also upload your JavaScript through the Apigee UI proxy editor. JavaScript source files must always have a `.js` extension. See [Supported software and supported versions](https://docs.apigee.com/release/supported-software) for the currently supported version of JavaScript. ### Video Watch a short video to learn how to create a custom policy extension using the JavaScript policy. ### Samples ### Rewrite the target URL Here's a common use case: extracting data from a request body, storing it in a flow variable, and using that flow variable elsewhere in the proxy flow. Let's say you have an app where the user enters their name in an HTML form and submits it. You want the API proxy to extract the form data and dynamically add it to the URL used to call the backend service. How would you do this in a JavsScript policy? **Note:** If you want to try out this example, we assume you've created a new proxy in the proxy editor. When you create it, just give it a backend service URL of: http://www.example.com. For this example, we're going to rewrite the backend URL dynamically. If you don't know how to create a new proxy, refer to the getting started tutorial. . 1. In Edge UI, open the proxy that you created in the proxy editor. 2. Select the **Develop** tab. 3. From the New menu, select **New Script**. 4. In the dialog, select JavaScript and give the script a name, like `js-example`. 5. Paste the following code in the code editor and save the proxy. The important thing to notice is the `context` object. This object is available to the JavaScript code anywhere in the proxy flow. It's used to obtain flow-specific constants, to call useful get/set methods, and for more operations. This object part is of Edge's [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model). Note, too, that the `target.url` flow variable is a built-in, read/write variable that is accessible in the Target Request flow. When we set that variable with the API URL, Edge makes its backend call to that URL. We've essentially rewritten the original target URL, which was whatever you specified when you created the proxy (e.g., http://www.example.com). ```javascript if (context.flow=="PROXY_REQ_FLOW") { var username = context.getVariable("request.formparam.user"); context.setVariable("info.username", username); } if (context.flow=="TARGET_REQ_FLOW") { context.setVariable("request.verb", "GET"); var name = context.getVariable("info.username"); var url = "http://mocktarget.apigee.net/" context.setVariable("target.url", url + "?user=" + name); } ``` 6. From the New Policy menu, select **JavaScript**. 7. Give the policy a name, like `target-rewrite`. Accept the defaults, and save the policy. 8. If you select the Proxy Endpoint Preflow in the Navigator, you'll see that the policy was added to that flow. 9. In the Navigator, select the **Target Endpoint PreFlow** icon. 10. From the Navigator, drag the JavaScript policy onto the Request side of the Target Endpoint in the flow editor. 11. Save. 12. Call the API like this, substituting your correct org name and proxy name as appropriate: ```javascript curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example ``` One final thing, let's take a look at the XML definition for the JavaScript policy used in this example. The important thing to note is that the `` element is used to specify the JavaScript source file to execute. This same pattern is used for any JavaScript source file: `jsc://filename.js`. If you're JavaScript code requires includes, you can use one or more `` elements to do that, as described later in this reference. ```javascript target-rewrite jsc://js-example.js ``` ### Retrieve property value from JavaScript You can add a `` element in configuration, then retrieve the element's value with JavaScript at runtime. Use the element's `name` attribute to specify the name with which to access the property from JavaScript code. The `` element's value (the value between the opening and closing tags) is the literal value that will be received by the JavaScript. In JavaScript, you retrieve the policy property value by accessing it as a property of the `Properties` object, as in the following: - Configure the property. Here, the property value is the variable name `response.status.code`. ```javascript JavascriptURLRewrite response.status.code jsc://JavascriptURLRewrite.js ``` - Retrieve the property with JavaScript. Here, the retrieved value -- a variable name -- is then used by the `getVariable` function to retrieve the variable's value. ```javascript var responseCode = properties.source; // Returns "response.status.code" var value = context.getVariable(responseCode); // Get the value of response.status.code context.setVariable("response.header.x-target-response-code", value); ``` ### Handling errors For examples and a discussion of error handling techniques that you can use in a JavaScript callout, see [this post in the Apigee Community](https://discuss.google.dev/t/correct-way-to-return-error-from-javascript-policy/12402). Suggestions offered in the Apigee Community are for information only and do not necessarily represent best practices recommended by Apigee. *** ** * ** *** ## Element reference The element reference describes the elements and attributes of the JavaScript policy. ```javascript JavaScript 1 propertyValue trueFalse trueFalse ref://keystoreRef keyAlias ref://truststoreRef jsc://a-javascript-library-file jsc://my-javascript-source-file insert_js_code_here ``` ## \ Attributes ```javascript ``` The following attributes are specific to this policy. | Attribute | Description | Default | Presence | |---|---|---|---| | timeLimit | Specifies the maximum time (in milliseconds) that the script is permitted to execute. For example, if a limit of 200 ms is exceeded, the policy throws this error: `Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms`. **Note:** For free trial accounts, execution time is limited to 200 ms. | N/A | Required | The following table describes attributes that are common to all policy parent elements: | Attribute | Description | Default | Presence | |---|---|---|---| | `name` | The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `` element to label the policy in the management UI proxy editor with a different, natural-language name. | N/A | Required | | `continueOnError` | Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. | false | Optional | | `enabled` | Set to `true` to enforce the policy. Set to `false` to *turn off* the policy. The policy will not be enforced even if it remains attached to a flow. | true | Optional | | `async` | This attribute is deprecated. | false | Deprecated | ## \ element Use in addition to the `name` attribute to label the policy in the management UI proxy editor with a different, natural-language name. ``` Policy Display Name ``` | Default | N/A If you omit this element, the value of the policy's `name` attribute is used. | | Presence | Optional | | Type | String | |---|---| ## \ element Specifies a JavaScript library file to be loaded as dependency to the main JavaScript file specified with the `` or `` element. The scripts will be evaluated in the order in which they are listed in the policy. Your code can use the objects, methods, and properties of the [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model). Include more than one JavaScript dependency resource with additional `` elements. > [!WARNING] > **Warning:** If your JavaScript files are stored at the organization or environment level, be sure they were uploaded correctly with cURL using the `-F` option or as a file attachment through a REST client. Content-Type is `multipart/form-data`. For more information, see [Resource files](https://docs.apigee.com/api-platform/develop/resource-files). ```javascript jsc://my-javascript-dependency.js ``` |---|---| | **Default:** | None | | **Presence:** | Optional | | **Type:** | String | ### Example See the Basic Example in the [Samples](https://docs.apigee.com/api-platform/reference/policies/javascript-policy#samples) section. ## \ element Specifies a property you can access from JavaScript code at runtime. ```javascript propertyValue ``` |---|---| | **Default:** | None | | **Presence:** | Optional | | **Type:** | String | ### Attributes | Attribute | Description | Default | Presence | |---|---|---|---| | name | Specifies the name of the property. | N/A | Required. | ### Example See the example in the [Samples](https://docs.apigee.com/api-platform/reference/policies/javascript-policy#samples) section. ## \ element Specifies the main JavaScript file that will execute in the API flow. You can store this file at the API proxy scope (under `/apiproxy/resources/jsc` in the API proxy bundle or in the Scripts section of the API proxy editor's Navigator pane), or at the organization or environment scopes for reuse across multiple API proxies, as described in [Resource files](https://docs.apigee.com/api-platform/develop/resource-files). Your code can use the objects, methods, and properties of the [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model). ```javascript jsc://my-javascript.js ``` |---|---| | **Default:** | None | | **Presence:** | Either `` or `` is required. If `` and `` are both present `` is ignored. | | **Type:** | String | ### Example See the Basic Example in the [Samples](https://docs.apigee.com/api-platform/reference/policies/javascript-policy#samples) section. ## \ element Allows you to insert JavaScript directly into the policy's XML configuration. The inserted JavaScript code executes when the policy executes in the API flow. |---|---| | **Default:** | None | | **Presence:** | Either `` or `` is required. If `` and `` are both present `` is ignored. | | **Type:** | String | ### Example ```javascript specialheader json_stringified var varname = 'request.header.' + properties.inboundHeaderName + '.values.string'; var h = context.getVariable(varname); if (h) { h = JSON.parse(h); h.augmented = (new Date()).valueOf(); var v = JSON.stringify(h, null, 2) + '\n'; // further indent var r = new RegExp('^(\S*)','mg'); v= v.replace(r,' $1'); context.setVariable(properties.outboundVariableName, v); } ``` ## \ element Specifies the properties used to configure TLS for all HTTP client instances created by the JavaScript policy. ```javascript trueFalse trueFalse ref://keystoreRef keyAlias ref://truststoreRef ``` |---|---| | **Default:** | None | | **Presence:** | Optional | | **Type:** | String | The process of configuring TLS for an HTTP client is the same process that you use to configure TLS for a TargetEndpoint/TargetServer. See [Configuring TLS from Edge to the backend](https://docs.apigee.com/api-platform/system-administration/configuring-ssl-edge-backend-service) for more information. ## Usage notes A JavaScript policy contains no actual code. Instead, a JavaScript policy references a JavaScript 'resource' and defines the Step in the API flow where the JavaScript executes. You can upload your script through the Management UI proxy editor, or you can include it in the `/resources/jsc` directory in API proxies that you develop locally. > [!WARNING] > **Warning:** System calls are not permitted by the security model. For example: internal file system reads or writes, or getting current user info, the process list, or CPU/memory utilization. Although some such calls may be functional, they are unsupported and liable to be actively disabled at any time. For forward compatibility, you should avoid making such calls in your code. ## Debugging JavaScript policy code Use the **print()** function to output debug information to the transaction output panel in the Trace Tool. For details and examples, see Debug with JavaScript **print()** statements. To view print statements in Trace: 1. Open the Trace Tool and start a trace session for a proxy that contains your JavaScript policy. 2. Call the proxy. 3. In the Trace Tool, click **Output from all Transactions** to open the output panel. ![](https://docs.apigee.com/static/api-platform/images/output-transactions.png) 4. Your print statements will appear in this panel. You can use the print() function to output debug information to the [Trace tool](https://docs.apigee.com/api-platform/debug/using-trace-tool-0). This function is available directly through the JavaScript object model. For details, see "[Debug JavaScript with print() statements](https://docs.apigee.com/api-platform/reference/javascript-object-model#debug)". ## 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: ```javascript context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name")) ``` The context object is part of the Apigee Edge [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model). ## Error reference This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see [What you need to know about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling faults](https://docs.apigee.com/api-platform/fundamentals/fault-handling). ### Runtime errors These errors can occur when the policy executes. > [!IMPORTANT] > Need help resolving an error? Click in the Fix column for detailed troubleshooting information. > > Use [API Monitoring](https://docs.apigee.com/api-monitoring) to investigate fault codes and diagnose issues faster. | Fault code | HTTP status | Cause | Fix | |---|---|---|---| | `steps.javascript.ScriptExecutionFailed` | 500 | The JavaScript policy can throw many different types of ScriptExecutionFailed errors. Commonly seen types of errors include [RangeError](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/javascript-runtime-errors#range_error), [ReferenceError](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/javascript-runtime-errors#reference_error), [SyntaxError](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/javascript-runtime-errors#syntax_error), [TypeError](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/javascript-runtime-errors#type_error), and [URIError](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/javascript-runtime-errors#uri_error). | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/javascript-runtime-errors#scriptexecutionfailed) | | `steps.javascript.ScriptExecutionFailedLineNumber` | 500 | An error occurred in the JavaScript code. See the fault string for details. | N/A | | `steps.javascript.ScriptSecurityError` | 500 | A security error occurred when the JavaScript executed. See the fault string for details. | N/A | ### Deployment errors These errors can occur when you deploy a proxy containing this policy. > [!IMPORTANT] > Need help resolving an error? Click next to the error's cause description to visit the troubleshooting page. | Error name | Cause | Fix | |---|---|---| | `InvalidResourceUrlFormat` | If the format of the resource URL specified within the `` or the `` element of the JavaScript policy is invalid, then the deployment of the API proxy fails. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/javascript-deployment-errors#invalidresourceurlformat) | | `InvalidResourceUrlReference` | If the `` or the `` elements refer to a JavaScript file that does not exist, then the deployment of the API proxy fails. The referenced source file must exist either the API proxy, environment, or organization level. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/javascript-deployment-errors#invalidresourceurlreference) | | `WrongResourceType` | This error occurs during deployment if the `` or the `` elements of the JavaScript policy refer to any resource type other than **jsc** (JavaScript file). | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/javascript-deployment-errors#wrongresourcetype) | | `NoResourceURLOrSource` | The deployment of the JavaScript policy can fail with this error if the `` element is not declared or if the resource URL is not defined within this element. `` element is a mandatory element. Or, The `` element is declared but the resource URL is not defined within this element. The `` element is optional but if declared, the resource URL must be specified within the `` element. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/javascript-deployment-errors#noresourceurlorsource) | ### Fault variables These variables are set when this policy triggers an error at runtime. For more information, see [What you need to know about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors). | Variables | Where | Example | |---|---|---| | `fault.name="fault_name"` | fault_name is the name of the fault, as listed in the [Runtime errors](https://docs.apigee.com/api-platform/reference/policies/javascript-policy#runtime-errors) table above. The fault name is the last part of the fault code. | `fault.name Matches "ScriptExecutionFailed"` | | `javascript.policy_name.failed` | policy_name is the user-specified name of the policy that threw the fault. | `javascript.JavaScript-1.failed = true` | ### Example error response > [!NOTE] > **Note:** For error handling, the best practice is to trap the `errorcode` part of the error response. Do not rely on the text in the `faultstring`, because it could change. ```javascript { "fault": { "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"", "detail": { "errorcode": "steps.javascript.ScriptExecutionFailed" } } } ``` ### Example fault rule ```javascript AM-CustomErrorResponse (fault.name Matches "ScriptExecutionFailed") (javascript.JavaScript-1.failed = true) ```
## Schema Each policy type is defined by an XML schema (`.xsd`). For reference, [policy schemas](https://github.com/apigee/api-platform-samples/tree/master/schemas/policy) are available on GitHub. ## Related topics - [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model) - For instructions, policy samples, and JavaScript samples, see [Programming API proxies with JavaScript](https://docs.apigee.com/api-platform/samples/cookbook/programming-api-proxies-javascript). ## Apigee Community articles You can find these related articles on the [Apigee Community](https://discuss.google.dev/c/google-cloud/cloud-apigee/104): - [How to handle multi-value headers in Javascript](https://discuss.google.dev/t/how-to-handle-multi-value-headers-in-javascript/17458)?