SAS Visual Analytics third party visualizations

This project contains code samples that can be used as data-driven content within a SAS Visual Analytics (VA) report. For additional information, see Programming Considerations for Data-Driven Visualizations.


util/messagingUtil.js

It contains the functions you need to send/receive messages to/from SAS Visual Analytics. You must include the following line in the <head> of the web page:

<script type="text/javascript" src="../util/messagingUtil.js"></script>

setOnDataReceivedCallback

Sets a callback function to handle messages received from VA.

Usage:

va.messagingUtil.setOnDataReceivedCallback(callback)

postSelectionMessage

Sends back to VA a message containing selections made in the third-party visualization. VA will use that information to either filter or select (brush) other report objects, depending on the Actions defined between the data-driven object and other VA report objects. It leverages function postMessage internally.

Usage:

va.messagingUtil.postSelectionMessage(resultName, selectedRows)

postInstructionalMessage

Sends back to VA an instructional message. This message is displayed in the data-driven content object in the VA report and is useful for sending text messages back to report authors informing required roles, their assignment order, types, etc. It leverages function postMessage internally.

Usage:

va.messagingUtil.postInstructionalMessage(resultName, strMessage)

postMessage

Sends back a message to VA.

Usage:

va.messagingUtil.postMessage(objMessage)

getUrlParams

Extracts parameter values assigned directly in the Data-Driven Content URL.

Usage:

value = va.messagingUtil.getUrlParams(name)

util/contentUtil.js

It contains the functions you need to validate the data received from VA. You must include the following line in the <head> of the web page:

<script type="text/javascript" src="../util/contentUtil.js"></script>

setupResizeListener

Sets a callback function to handle window resizing events.

Usage:

va.contentUtil.setupResizeListeners(callback)

validateRoles

Checks if the data received from VA have all the columns (number, sequence, and type) required for the visualization.

Usage:

isValid = va.contentUtil.validateRoles(resultData, expectedTypes, optionalTypes)

initializeSelections

Uses the message received from VA to extract information about selections made in VA objects. After extracting selection information, the “brush” column is removed from the message.

Usage:

selections = va.contentUtil.initializeSelections(resultData)

convertDateColumns

Transforms the message received from VA so that date values (represented as strings) are converted to Date objects. This standardizes date representation and might be helpful to support further transformations and formatting on dates.

Usage:

va.contentUtil.convertDateColumns(resultData)

getVAParameters

Extracts parameter information from message received from VA.

Usage:

parameters = va.messagingUtil.getVAParameters(resultData)

thirdPartyHelpers/google.js

It contains helper functions you most likely need with Google Charts. You must include the following lines in the <head> of the web page:

<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript" src="../thirdPartyHelpers/google.js"></script>

createDataTable

Uses the data and columns keys from the VA message to create a DataTable object. Google Charts take DataTable as input data for its charts, but in addition to that, DataTable offers a series of methods that can help with table manipulation. More information on DataTable can be found here.

Usage:

dataTable = va.googleHelper.createDataTable(resultData)

formatData

Uses the columns metadata within the message received from VA to update column formats in a DataTable object. Only numeric and date columns are affected. Supported formats are: DOLLAR, COMMA, F, BEST, and PERCENT for numeric, and MONYY, MMYY, MMDDYY, DATE, DDMMYY, WORDDATE, YYMMDD, and DATETIME for dates. Other column formats are kept unchanged.

Usage:

va.googleHelper.formatData(dataTable, resultData)

formatAxis

Uses the columns metadata within the message received from VA to update/add a vAxis.format or a hAxis.format in the Google Charts options variable. Only numeric columns are affected. Supported VA formats are: DOLLAR, COMMA, F, BEST, and PERCENT. Other column formats are kept unchanged.

Usage:

va.googleHelper.formatAxis(axis, options, resultData)

It contains helper functions you most likely need with D3 charts. You must include the following line in the <head> of the web page:

<script type="text/javascript" src="../thirdPartyHelpers/d3.js"></script>

configureFormatter

Uses the columns metadata within the message received from VA to configure D3 formats. Only numeric columns are affected. Supported VA formats are: DOLLAR, COMMA, F, BEST, and PERCENT. Other columns formats are kept unchanged.

Usage:

formatter = va.d3Helper.configureFormatter(resultData)

configureAxisFormatter

Uses the columns metadata within the message received from VA to configure D3 formats. This function is similar to va.d3Helper.configureFormatter, but the format returned doesn’t have any decimal places. Only numeric columns are affected. Supported VA formats are: DOLLAR, COMMA, F, BEST, and PERCENT. Other columns formats are kept unchanged.

Usage:

axisFormatter = va.d3Helper.configureAxisFormatter(resultData)

It contains helper functions you most likely need with C3 charts. You must include the following line in the <head> of the web page:

<script type="text/javascript" src="../thirdPartyHelpers/c3.js"></script>

configureChartData

Uses the data and columns keys from the VA message to create the chart data JSON object, necessary to draw the C3 chart. If necessary, this function also sets the appropriate configuration to unload the existing chart prior to re-drawing it.

Usage:

chartData = va.c3Helper.configureChartData(resultData, chartType, previousConfig)

util/casUtil.js

It contains the functions you need to create CAS sessions and execute CAS actions from SAS Visual Analytics. Those functions were designed and tested with VA 8.3 (SAS Viya 3.4) and above, up to VA 8.5 (SAS Viya 3.5). Internal implementation and REST APIs used may differ depending the the SAS Viya version. Decisions are made based on the VA version detected. You must include the following line in the <head> of the web page:

<script type="text/javascript" src="../util/casUtil.js"></script>

startCasSession

Leverages SAS Viya REST API to create a CAS session that you can use to execute CAS actions. It uses the following endpoints internally: VA 8.3 and above on SAS Viya 3.4: /casManagement/servers and /casProxy/servers/<serverName>/cas/sessions VA 8.5 on SAS Viya 3.5: /casManagement/servers and /casManagement/servers/<serverName>/sessions

Usage:

va.casUtil.startCasSession().then(function(sessionInfo){...})

Note: If you have more than one server, it returns the first one on the list.

casAction

Leverages SAS Viya REST API to execute CAS actions by using the following endpoint: /casProxy/servers/<serverName>/cas/sessions/<sessId>/actions/<action>

Usage:

va.casUtil.casAction(serverName, sessId, action, data).then(function(response){...})

getCasServerName

Leverages SAS Viya REST API to obtain the CAS server name. It uses the following endpoint internally: /casManagement/servers

Usage:

va.casUtil.getCasServerName().then(function(serverInfo){...})

Note: If you have more than one server, it returns the first one on the list.

getCsrfToken

Leverages SAS Viya REST API to obtain the CSRF token for a specified service. It uses the following endpoint internally: /<service>/

Usage:

va.casUtil.getCsrfToken(service).then(function(token){...})

Note: Token values for each service are cached internally for future calls to this function.

getAppVersion

Leverages SAS Viya REST API to obtain the version for a specified application. It uses the following endpoint internally: /<app>/apiMeta

Usage:

va.casUtil.getAppVersion(app).then(function(version){...})

util/jobUtil.js

It contains utility functions to support easier integration between SAS Visual Analytics and SAS Jobs. You must include the following line in the <head> of the web page:

<script type="text/javascript" src="../util/jobUtil.js"></script>

PrepareVADataForSASJobs

Transforms the data received from VA and adds extra format information for SAS Jobs to use.

Usage:

va.jobUtil.PrepareVADataForSASJobs(resultData)

Notes:

pingApp

Pings the app to keep it alive.

Usage:

va.jobUtil.pingApp(app)

keepAppAlive

Calls pingApp on 1 minute intervals to keep the application alive.

Usage:

va.jobUtil.keepAppAlive(app)