{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":35825,"path":"now-intelligence/performance-analytics/pa-scripts.md","title":"Scripting in Performance Analytics","bundle":null,"doc_type":null,"release":"australia","body":"\n# Scripting in Performance Analytics\n\nPerformance Analytics provides several script objects for use in scripts and APIs for querying Performance Analytics data. The scripts serve as breakdown mappings or to calculate a value from an indicator.\n\n## Tips on scripts\n\n-   In general, use scripts only to support indicators like Age with date processing, using the `score_start` and `score_end` variables.\n-   Limit unnecessary fields. Every time you include an extra dot-walked field, you add an extra join to the query.\n-   Try to replace manual breakdowns with [database views](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/performance-analytics/performance-analytics-glossary.md) for better performance.\n-   Try to use script includes for common functions. For more information, see [Script includes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/scripts/c_ScriptIncludes.md).\n-   If the data is not structured in a way you need for reporting, try adding 'reporting fields' to the operational tables instead of creating scripts. For more information, see this [Community post](https://community.servicenow.com/community?id=community_blog&sys_id=2f99990fdbee5b00fece0b55ca9619fb).\n-   If you are running a background script that queries the Performance Analytics scores or snapshots tables, you cannot access data about a scoped application unless you have an appropriate role for that application.\n\n**Warning:** Try not to use GlideRecords or GlideAggregates in Performance Analytics scripts or formula indicators. While sometimes you must use these operations to get what you want, they are expensive, potentially running hundreds of thousands of times. Be certain that no alternative exists before you use them.\n\n## Breakdown mapping and indicator scripts\n\nA [breakdown mapping](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/performance-analytics/performance-analytics-glossary.md) script typically returns either a sys\\_id of a breakdown element or an integer to put the score in a bucket. Indicator scripts return a score calculated from one or more fields. The same script can serve both as a breakdown mapping script and as an indicator script.\n\n## Breakdown script\n\nFor example, consider the provided Incident.Age.Days script, which uses the `opened_at` field from the incident table. This script serves as a breakdown mapping for the Age breakdown, which uses the Incident Age Ranges \\(Days\\) [bucket group](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/performance-analytics/performance-analytics-glossary.md) as the breakdown source.\n\n```\nvar diff=function(x,y){return y.dateNumericValue() - x.dateNumericValue();};\nvar days=function(x,y){return diff(x,y)/(24*60*60*1000);};\ndays(current.opened_at, score_end);\n```\n\nIn this example, `current.opened_at` gets the timestamp of when the currently evaluated record was opened. The `score_end` [script variable](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/performance-analytics/pa-scripts.md) comes from the [data collector](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/performance-analytics/performance-analytics-glossary.md) and is bound to the period being collected. For example, if a monthly indicator is being collected, the `score_end` is the end of the month. Here the timestamp of when the incident was opened is subtracted from the timestamp of the end of the collection period and the result is converted to days.\n\nThis example includes the `Incident.opened_at` field, which is specified in the **Fields** field for this script. You can use `score_start` and `score_end` without defining them in the **Fields** field.\n\n**Parent Topic:**[Configure Performance Analytics advanced features](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/performance-analytics/c_PADataArchitecture.md)\n\n**Related topics**  \n\n\n[Create a breakdown mapping on a breakdown record](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/performance-analytics/t_CrtBkdnBreakdownMpngs.md)\n\n[Server Scoped API List](https://developer.servicenow.com/dev.do#!/reference/api/tokyo/server)\n\n## Create a script in Performance Analytics\n\nTo create a script, first select the facts table to which the script applies and explicitly select any fields.\n\n### Before you begin\n\nRole required: admin, pa\\_admin. To access data for scoped applications in Performance Analytics tables, you also need the appropriate admin role for that application.\n\n### Procedure\n\n1.  Navigate to **All** > **Platform Analytics Administration** > **Indicators** > **Scripts** and click **New**.\n\n2.  Give the script a descriptive **Name**.\n\n3.  Select the **Facts table** that the script applies to.\n\n    Only indicators that use the same facts table can use this script.\n\n4.  Select the fact table **Fields**, if any, that will be used in the script.\n\n    You select fields by their labels.\n\n5.  Write the script.\n\n    The script must conform to the following relationships and restrictions:\n\n    -   You can include only the fields that are selected in this form and script variables. For more information, see the section about Performance Analytics variables.\n    -   When you use a field in the script, you use the column name. If necessary, look up the column name in the facts table.\n    -   When you use a field from a database view, you must include the prefix. For example, the incident\\_sla database view includes the task\\_sla table, with the prefix taskslatable. Task\\_sla includes the business\\_duration column. To use the business\\_duration field from the incident\\_sla database view, write it as taskslatable\\_business\\_duration. If you do not have access to the database view, ask your system administrator to find the prefix for you.\n\n### What to do next\n\nAfter you create the script, create a breakdown mapping or indicator that uses the script. You can open a breakdown mapping or indicator form by clicking **New** in either the breakdown mapping or indicator tab. The breakdown mappings and indicators that use this script are listed in those tabs.\n\n## Performance Analytics variables\n\nSeveral variables are available for use in Performance Analytics scripts and formula indicators.\n\nYou can use the following variables in Performance Analytics scripts and formulas.\n\n-   `score_start`: First second of the day of the first indicator score collection. For scripts, the time is calculated based on the difference between the time zone of the Run As user for the collection job and the database time zone, which is GMT. For formulas, the time is calculated based on the difference between the time zone of the user who executes the formula and GMT. A user executes a formula by viewing the formula indicator in a dashboard widget or on the Analytics Hub.\n-   `score_end`: Last second of the day of the last indicator score collection. The time is calculated the same way as for `score_start`.\n-   `pa`: A formula variable, not usable in scripts, that provides a set of Analytics Hub attributes and methods.\n\nIn scripts, the score collection start and end variables are GlideElementGlideObject objects. You can obtain a GlideDateTime object from these variables by calling getGlideObject\\(\\), such as in this example: `gs.log(\"Score main = \" + score_end.getGlideObject().getDayOfWeek());`\n\nIn formulas, the score collection start and end variables already are GlideDateTime objects. Therefore, you can use the variables directly without calling getGlideObject\\(\\), such as in this example: `gs.log(\"Score main = \" + score_end.getDayOfWeek());`\n\nThe values of the start and end variables are bound to the period being collected. For example, if a monthly indicator is being collected, the `score_end` is the end of the month.\n\nThe `score_start` and `score_end` values are calculated based on the time zone of the relevant user. For Performance Analytics scripts, this is the Run As time zone for the collection job. For formulas, this is the time zone of the user who views the formula indicator in a dashboard widget or the Analytics Hub. Users in different time zones therefore may have different dates for `score_start` and `score_end` in a formula.\n\n**Related topics**  \n\n\n[Get analytics methods in formulas](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/performance-analytics/get-indicator-analytics.md)\n\n[Changes to score\\_start/end because of different user time zones]()\n\n"}}