{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":766,"path":"api-reference/server-api-reference/FinancialsWidgetUtilScopedAPI.md","title":"FinancialsWidgetUtil - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# FinancialsWidgetUtil- Scoped\n\nThe FinancialsWidgetUtil script include provides methods to customize widgets in the **Financials** section of Project Workspace and Strategic Planning Workspace.\n\nThe following widgets are available in Project Workspace and Strategic Planning Workspace by default.\n\n- Budget\n- Estimate at Completion\n- Planned Cost\n- Actual Cost to Date\n\nYou can use the FinancialsWidgetUtil script include to add child widgets that show values for a specified time period or expense type.\n\n\\[Omitted image \"financials-widgets.png\"\\] Alt text: This screenshot shows widgets for Budget, Estimate at Completion, Budget vs EAC Variance, Planned Cost, and Actual Cost to Date.\n\nIn this example from Project Workspace, the Planned Cost widget has child widgets that show CapEx and OpEx values, while the Budget widget doesn't have any child widgets.\n\nTo use this script include, [create a child widget](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-business-management/configure-widget-project-financials.md) with one of the available financials widgets as the parent. Use the methods from this script include in the **Script** field of the child widget record.\n\nThe FinancialsWidgetUtil script include requires the Financials Core application \\(sn\\_invst\\_pln\\), as well as the Strategic Planning application \\(sn\\_apw\\_advanced\\) or Project Workspace application \\(sn\\_pw\\). This script include is provided within the `sn_invst_pln` namespace.\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## FinancialsWidgetUtil - FinancialsWidgetUtil\\(GlideRecord investmentGr, Object timeScope, String expenseType\\)\n\nInstantiates a FinancialsWidgetUtil object.\n\nThis object is used to get aggregate values such as budget and planned cost for an investment.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\ninvestmentGr\n\n\n\n[GlideRecord](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideRecordScopedAPI.md)\n\n\n\nInvestment to get aggregate values for.Table: Investment \\[sn\\_invst\\_pln\\_invst\\_investment\\]\n\n
\n\ntimeScope\n\n\n\nObject\n\n\n\nList of fiscal periods to use as the start and end dates for the aggregation.```\n{ \n \"startFiscalPeriodSysId\": \"String\", \n \"endFiscalPeriodSysId\": \"String\" \n} \n```\n\n
\n\ntimeScope.startFiscalPeriodSysId\n\n\n\nString\n\n\n\nSys\\_id of the fiscal period to use as the start date for the aggregation.Table: Fiscal Period \\[fiscal\\_period\\]\n\n
\n\ntimeScope.endFiscalPeriodSysId\n\n\n\nString\n\n\n\nSys\\_id of the fiscal period to use as the end date for the aggregation.Table: Fiscal Period \\[fiscal\\_period\\]\n\n
\n\nexpenseType\n\n\n\nString\n\n\n\nOptional. Type of expense to include in the aggregation, such as capital expenditure \\(CapEx\\) or operating expense \\(OpEx\\).Valid values:\n\n- capex\n- opex\n\n
This example instantiates a FinancialsWidgetUtil object that can be used to return aggregate values for an investment where the expense type is CapEx and the time period is `context.timeScope`.\n\n```\nvar context = JSON.parse(context);\nvar investment = context.investment;\n(function initializeFWU() {\n var invGr = new GlideRecord('sn_invst_pln_invst_investment');\n if (invGr.get(investment.sys_id)) {\n var capexCost = new sn_invst_pln.FinancialsWidgetUtil(invGr, context.timeScope, 'capex');\n }\n})();\n```\n\n## FinancialsWidgetUtil - getActuals\\(\\)\n\nReturns the actual cost for any planning items and work items linked to an investment.\n\nTo use this method, [create a child widget](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-business-management/configure-widget-project-financials.md) with the Actual Cost to Date widget as the parent. Use this method in the **Script** field of the child widget record.\n\nThe actual cost returned by this method is for the time period and expense type specified when instantiating the FinancialsWidgetUtil object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nObject containing the display value and value for the actual cost.\n\n ```\n{ \n \"displayValue\": \"String\", \n \"value\": Number\n}\n```\n\n
\n\n<Object>.displayValue\n\n\n\nDisplay value of the actual cost, such as `$1.00 K`.Data type: String\n\n
\n\n<Object>.value\n\n\n\nValue of the actual cost, such as `1000`.Data type: Number\n\n
This example adds a child widget to the Actual Cost to Date widget that shows the actual cost for OpEx only.\n\n```\nvar context = JSON.parse(context);\nvar investment = context.investment;\n(function getCost() {\n var invGr = new GlideRecord('sn_invst_pln_invst_investment');\n if (invGr.get(investment.sys_id)) {\n var opexCost = new sn_invst_pln.FinancialsWidgetUtil(invGr, context.timeScope, 'opex').getActuals();\n return {\n displayValue: PPMCurrencyHelper.getFormattedAmountWithCurrency(opexCost.value),\n value: opexCost.value\n };\n }\n})();\n```\n\n## FinancialsWidgetUtil - getBudget\\(\\)\n\nReturns the budget for any planning items and work items linked to an investment.\n\nTo use this method, [create a child widget](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-business-management/configure-widget-project-financials.md) with the Budget widget as the parent. Use this method in the **Script** field of the child widget record.\n\nThe budget returned by this method is for the time period and expense type specified when instantiating the FinancialsWidgetUtil object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nObject containing the display value and value for the budget.\n\n ```\n{ \n \"displayValue\": \"String\", \n \"value\": Number\n}\n```\n\n
\n\n<Object>.displayValue\n\n\n\nDisplay value of the budget, such as `$2.50 K`.Data type: String\n\n
\n\n<Object>.value\n\n\n\nValue of the budget, such as `2500`.Data type: Number\n\n
This example adds a child widget to the Budget widget that shows the budget for OpEx only.\n\n```\nvar context = JSON.parse(context);\nvar investment = context.investment;\n(function getCost() {\n var invGr = new GlideRecord('sn_invst_pln_invst_investment');\n if (invGr.get(investment.sys_id)) {\n var opexCost = new sn_invst_pln.FinancialsWidgetUtil(invGr, context.timeScope, 'opex').getBudget();\n return {\n displayValue: PPMCurrencyHelper.getFormattedAmountWithCurrency(opexCost.value),\n value: opexCost.value\n };\n }\n})();\n```\n\n## FinancialsWidgetUtil - getEAC\\(\\)\n\nReturns the estimate at completion \\(EAC\\) value for any planning items and work items linked to an investment.\n\nTo use this method, [create a child widget](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-business-management/configure-widget-project-financials.md) with the Estimate at Completion widget as the parent. Use this method in the **Script** field of the child widget record.\n\nThe EAC value returned by this method is for the time period and expense type specified when instantiating the FinancialsWidgetUtil object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nObject containing the display value and value for the EAC.\n\n ```\n{ \n \"displayValue\": \"String\", \n \"value\": Number\n}\n```\n\n
\n\n<Object>.displayValue\n\n\n\nDisplay value of the EAC, such as `$2.38 K`.Data type: String\n\n
\n\n<Object>.value\n\n\n\nValue of the EAC, such as `2380`.Data type: Number\n\n
This example adds a child widget to the Estimate at Completion widget that shows the EAC for OpEx only.\n\n```\nvar context = JSON.parse(context);\nvar investment = context.investment;\n(function getCost() {\n var invGr = new GlideRecord('sn_invst_pln_invst_investment');\n if (invGr.get(investment.sys_id)) {\n var opexCost = new sn_invst_pln.FinancialsWidgetUtil(invGr, context.timeScope, 'opex').getEAC();\n return {\n displayValue: PPMCurrencyHelper.getFormattedAmountWithCurrency(opexCost.value),\n value: opexCost.value\n };\n }\n})();\n```\n\n## FinancialsWidgetUtil - getPlannedCost\\(\\)\n\nReturns the planned cost for any planning items and work items linked to an investment.\n\nTo use this method, [create a child widget](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-business-management/configure-widget-project-financials.md) with the Planned Cost widget as the parent. Use this method in the **Script** field of the child widget record.\n\nThe planned cost returned by this method is for the time period and expense type specified when instantiating the FinancialsWidgetUtil object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nObject containing the display value and value for the planned cost.\n\n ```\n{ \n \"displayValue\": \"String\", \n \"value\": Number\n}\n```\n\n
\n\n<Object>.displayValue\n\n\n\nDisplay value of the planned cost, such as `$4.05 K`.Data type: String\n\n
\n\n<Object>.value\n\n\n\nValue of the planned cost, such as `4050`.Data type: Number\n\n
This example adds a child widget to the Planned Cost widget that shows the planned cost for OpEx only.\n\n```\nvar context = JSON.parse(context);\nvar investment = context.investment;\n(function getCost() {\n var invGr = new GlideRecord('sn_invst_pln_invst_investment');\n if (invGr.get(investment.sys_id)) {\n var opexCost = new sn_invst_pln.FinancialsWidgetUtil(invGr, context.timeScope, 'opex').getPlannedCost();\n return {\n displayValue: PPMCurrencyHelper.getFormattedAmountWithCurrency(opexCost.value),\n value: opexCost.value\n };\n }\n})();\n```\n\n"}}