Future ACP Features

Warning: These ACP Features described below are in development. These are initial descriptions to give you an idea of possible future features and for initial comment. They are (probably) not yet available in the current ACP release. And they may change before they are released. In fact, some may not get released in this form or at all.

Status may be:

Suggestion, may not yet be well-formed.
Draft spec
Draft specification to be reviewed
Specification reviewed and ready to implement
To test
Ready for internal testing. Should specify where version can be found, and a test model where needed.
To document
User document needs to be finalized
Normally, when a feature is released, the description and user documentation is moved from this page to the appropriate ACP page describing released features.

Async calls

Analytica functions that generate user dialog boxes have not been available in ACP. These include SpreadsheetOpen, ShowProgressBar, MsgBox, AskMsgNumber and AskMsgChoice. A new feature to support call backs from ADE to ACP is in development.

Fred, please put in a brief overview of how this works and why it requires polling, and what that means.

Note: The following CloudPlayerStyle attribute is no longer necessary, since asynchronous polling has been implemented as the default for ACP as of, {although it will not effect the functionality of ACP if you leave it in your model}:

"use_async_calls: yes"

Status: To test

Here is how they work in ACP:

A recent enhancement to ADE allows ADE to make callbacks to ACP. Usually, ACP initiates all function calls and ADE returns a result. In this case, it's the opposite. ADE initiates a function call and ACP returns the result. I'll illustrate this with an example. Now there's a callback in ADE called GetFileName(). Let's say you have a variable spread := spreadsheetOpen("", true). And you have a button which evaluates this variable.

When use_asyc_calls:yes is NOT specified or the cloudplayerstyle attribute for the model contains use_asyc_calls: no

  • When the button is clicked, the ACP client (i.e. shockwave file running in the browser) makes the SendCommand web service call to the ACP server. The ACP server in turn calls ADE's SendCommand() function and passes it the name of the button.
  • Then the ACP server will wait for the SendCommand function to return a result
  • Now the ACP server returns the result of the button click to the client. (This is synchronous programming.)

When use_asyc_calls: yes is specified

Note: This is now the default.

  • When the button is clicked, the ACP client makes a web service call to the ACP server called SendCommandAsync. The ACP server in turn calls ADE's SendCommand() function and passes it the name of the button. But the call to SendCommand is made asynchronously so SendCommandAsync web service returns immediately to the client and does not wait for the result from SendCommand().
  • After half a second, the client starts the polling. It calls the PollForWebServiceResultOrAdeCallBack web service repeatedly. It starts by calling this web service a half second after making the SendCommandAsync is called, and then continues calling this function every second.
  • ADE concurrently is executing the OnClick attribute which in turn executes SpreadsheetOpen(). ADE sees that SpreadsheetOpen needs to prompt for the spreadsheet file and so calls the GetFileName() callback.
  • ACP server receives the call back. This callback first sets a number of Session variables including 'timeToUploadSpreadsheet' and 'spreadsheetMessageCaption'. Then the GetFileName callback enters a loop which includes a line of code that checks for another session variable 'SpreadSheetFilePath'. Since 'SpreadSheetFilePath' is not yet set, then the function sleeps for half a second and continues looping for up to 240 loops. (to do: handle timeout and fine tune sleep interval and max number of loops)
  • Now in the web service, PollForWebServiceResultOrAdeCallBack, this function detects that the 'timeToUploadSpreadsheet' flag is set. And when it returns it tells the client.
  • Now the client presents the Message Box and File Upload dialog, and uploads the spreadsheet file to the server. (It also checks to see if the file already exists.)
  • After the file is uploaded, the client calls the checkForFileUploadDownloadError web service. It passes the fileName of the uploaded file as a parameter. If there's no error, the server sets the session variable 'SpreadSheetFilePath' to the path of the uploaded spreadsheet.
  • The GetFileName callback sees the 'SpreadSheetFilePath' is set so it stops looping and returns the path to ADE. ADE continues running the button OnClick.
  • When ADE finishes running the OnClick attribute of the button, it returns to the client. The client stores the result in another session variable 'sendCommandResult'
  • The web service PollForWebServiceResultOrAdeCallBack now sees 'sendCommandResult' is set, and returns the result to the client.
  • Now the client stops polling i.e. stops calling PollForWebServiceResultOrAdeCallBack every second. It also calls another web service which updates the diagram to show any results or meta-modeling changes that the button click caused.

SpreadsheetOpen in ACP

Status: To test

This feature is has been implemented and is being tested. A little background, the SpreadsheetOpen() has been working for a long time in ACP. You can use this function as follows (with or without use_async_calls: yes setting): SpreadsheetOpen('xyz.xlsx') and it will work fine provided that the spreadsheet 'xyz.xlsz' had already been uploaded to ACP.

The {default} "use_async_calls: yes" flag is needed when you want users be able to upload a spreadsheet file while a model is playing. E.g. "SpreadsheetOpen('DoesNotExist.xlsx')" or "SpreadSheetOpen('xyz.xlsx', showDialog:true)". In this case, if the "use_async_calls: yes" flag is present ACP will show a file upload dialog which will allow the user to upload and then open the spreadsheet file.

The spreadsheet file uploading and opening works fine in general, but we need to investigate interactions with and limits of Excel. Two things come to mind. One is that Excel locks files that it is currently using, so this might block another user from using the same spreadsheet at the same time, uploading a spreadsheet that is locked, deleting a spreadsheet that is locked etc. This is mainly a matter of giving an informative message of what's happening and coming up with some best practices when working with spreadsheets. Also, I often see a message in Excel that says you can't have two different spreadsheet files with the same name opened at the same time, so we need to test whether this limitation exists in ACP and decide how to handle it.

SpreadsheetSave in ACP

Status: To test

I don't believe SpreadsheetSave() needs to be mentioned here or if so only to state that this function does not involve an ADE callback and thus should work fine with or without the "use_async_calls: yes" setting. In Desktop Analytica, I don't believe you are ever prompted with a dialog for saving a spreadsheet so nor should you be in ACP.

Downloading a spreadsheet while playing a model in ACP is a different matter. There is a new feature which provides a way for downloading a spreadsheet (presumably with model results saved in it) by adding a flag to the CPS attribute of a button. E.g. if you want to download 'xyz.xlsx' you add "download_spreadsheet xyz.xlsx" to the CPS attribute of the button.

You can also do this "on the fly" in your model by having an OnClick attribute that sets this flag in the CPS attribute.

Added to CPS page, and What's new page.

AskMsgNumber and AskMsgChoice in ACP

Status: Spec

AskMsgNumber and AskMsgChoice are now possible to implement in ACP because of the ADE callbacks, but are a lower priority because nobody ever asks for these features, and it's not trivial to implemented them, so there would be significant opportunity cost to implementing and testing them. If someone has a model and they want one of these functions to work, please email awp@lumina.com and let us know.

See Also


You are not allowed to post comments.