GetResult (Application-Level)
The primary usage of this method is to perform a single calculation based on a series and return a set of calculated outputs. The method also includes parameters to indicate whether to save the corresponding values to the system, as well as support for Goal Seek calculations.
Authentication
This method requires an authentication token if the access level of the application is set to Restricted.
Request
Target Endpoint
POST /Api/Applications/GetResult
Parameters
|
Property Name |
Type |
Is Required? |
Description |
|---|---|---|---|
| ApplicationKey | String | Required | The application key, corresponding to your specific web service application. This constitutes the identifier for the requested resource. |
| Inputs | Array of Object
JSON Schema: Setting a single cell: { Value: [ [ { Value: “10” } ] ] } |
Required | Collection of cells or references that will be set as part of the request to the calculation engine.
The property name should correspond to a cell reference (e.g. WorksheetA!$A$4) or a named range. |
| Outputs | Array of String:
[ “CellE”, “CellF”, “CellG” ] |
Required | A list of outputs to be retrieved after calculations are done and sent back in the response.
Each item should correspond to a cell reference (e.g. WorksheetA!$A$4) or a named range. |
| GoalSeek | Object | Optional | The GoalSeek property contains input parameters required by the goal seek feature. The object’s properties can be found below. |
| SessionId | String | Optional | A session identifier, to be utilized in conjunction with the /OpenDedicatedSession and /CloseDedicatedSession methods. Details are outlined in the corresponding sections. |
| SaveInformation | Object | Optional | The SaveInformation property contains information about the save event. The object’s properties can be found below. |
Request Sample (Simple) (Restricted)
The sample below is a simple request to the GetResult method for a restricted application, clearly designated by the bearer token in the authorization header. The token was retrieved using an authentication request. The process of retrieving an access token is documented here.
Headers
POST /Api/Applications/GetResult HTTP/1.1 Authorization: Bearer Do3l_2l3uLdmYX76u-BufLzuuhFPOE-nRZDyU0adiFk1 Content-Type: application/json Host: dev7.pagos.com
Body (formatted)
{
"ApplicationKey": "d29d7bc4b204489180d0934346730448",
"Inputs": [
{
"Ref": "InputA",
"Value": [
[
{
"Value": "100"
}
]
]
},
{
"Ref": "InputB",
"Value": [
[
{
"Value": "200"
}
]
]
}
],
"Outputs": [
"SumOfInputs",
"ProductOfInputs"
]
}
Additional Specifications
Saving
Any web service application that intends to utilize the saving functionality must be converted using the SpreadsheetWeb wizard. The conversion does not need to include any user interface elements, only a single button with the Save functionality enabled and the cell mappings set up.
During the saving process, the system will access this metadata to determine which values from the workbook need to be saved and which tables and columns they need to be mapped to in the database. This includes values stored on secondary tables (i.e. one-to-many relationships) and files.
If a cell is not configured to be saved in the converted file’s metadata, that value will not be stored.
SaveInformation (Input) Members
|
Property Name |
Type |
Is Required? |
Description |
|---|---|---|---|
| Save | Boolean | Required | Whether to save the result to the database after the calculations have been completed.
A new record will be generated, unless the RecordId parameter is set, in which case the current calculation set will constitute an UPDATE to the existing record. |
| RecordId | Int? | Optional | If saving the record as an update (rather than a new record), this value should correspond to the underlying data record identifier. |
| SetRecordStatusIndex | Int? | Optional | If saving the record – whether create or update – this parameter can indicate what the status of the record should be. This is a 0-based index corresponding to the user-defined status types from the data page. |
| SetGroupId | Int? | Optional | If saving the record – whether create or update – this parameter should indicate the group that this record should be assigned to. This is based on the group’s system-generated identifier, which can be found from the Manage Groups page. |
| SetAssignedUserName | String | Optional | If saving the record – whether create or update – this parameter should indicate the user that this record should be assigned to. |
| UserName | String | Optional for Unrestricted Applications, Required for Restricted Applications | A plaintext string corresponding to a system user that is saving the result.
In order to use this parameter, your authentication token must be associated with an identifier that has the right to impersonateusers. |
Saving Files
When there are saving cell columns configured to store raw binary file data, the contents for this data can be submitted to the web service as a standard input string using the following format:
filename={0};filetype={1};filecontents={2}
Where the variables are defined as follows:
The {0} should be replaced with the file’s name.
The {1} should be replaced with the file’s extension.
The {2} should be the actual file contents as a Base64-encoded string.
For example, if you have a file stored in column named FileColumn, which has been mapped to a cell corresponding to the named range FileColumn, the file would be submitted to the API in the inputs section as follows:
Inputs: [
…
{
"Ref": "FileColumn",
"Value": [
[
{ "Value": "filename=my-cool-file;filetype=docx;filecontents={base64-contents}" }
]
]
}
…
]
When using the file saving feature, the Save flag on the SaveInformation object must be TRUE in order for those files to be retained in the system.
Request Sample (Save) (Restricted)
Headers
POST /Api/Applications/GetResult HTTP/1.1 Authorization: Bearer Do3l_2l3uLdmYX76u-BufLzuuhFPOE-nRZDyU0adiFk1 Content-Type: application/json Host: dev7.pagos.com
Body (formatted)
{
"SaveInformation": {
"Save": true,
"UserName": "ssweb"
},
"Inputs": [
{
"Ref": "Description",
"Value": [
[
{
"Value": "dummy text"
}
]
]
},
{
"Ref": "InputA",
"Value": [
[
{
"Value": "3"
}
]
]
},
{
"Ref": "TableInput",
"Value": [
[
{
"Value": "1"
},
{
"Value": "2"
},
{
"Value": "3"
}
],
[
{
"Value": "4"
},
{
"Value": "5"
},
{
"Value": "6"
}
]
]
}
],
"Outputs": [
"OutputA"
],
"ApplicationKey": "a4dcfb4f0464453b928ce1d6bcfb6aa3"
}
GoalSeekInformation (Input) Members
|
Property Name |
Type |
Is Required? |
Description |
|---|---|---|---|
| Enabled | Boolean | Required | Determines the execution of the goal seek algorithm during calculations. Setting this to TRUE will enable goal seek based on the other parameters. |
| TargetRef | String | Required | Determines the cell to be compared with the TargetValue between each iteration.
The property should correspond to a cell reference (e.g. WorksheetA!$A$4) or a named range. |
| ChangingRef | String | Required | Determines the cell to be changed between each iteration (in order for TargetRef to reach TargetValue).
The property should correspond to a cell reference (e.g. WorksheetA!$A$4) or a named range. |
| TargetValue | Double | Required | TargetValue property is the target value of the goal seek calculation. Iterations will stop when either the TargetRef cell value is equal to TargetValue or the MaxIterations limit is reached. |
| MaxIterations | Int | Optional | Maximum iterations to be run before reaching the target value. Iterations will stop regardless of the TargetValue if the MaxIterations is reached.
If not set, a maximum of 1000 iterations will be run. |
| MaxChange | Double | Optional | The maximum amount of change to be applied to ChangingRef between each iteration.
If not set, a maximum amount of 0.000001 will be used. |
Request Sample (GoalSeek) (Restricted)
Headers
POST /Api/Applications/GetResult HTTP/1.1 Authorization: Bearer Do3l_2l3uLdmYX76u-BufLzuuhFPOE-nRZDyU0adiFk1 Content-Type: application/json Host: dev7.pagos.com
{
"Inputs": [
{
"Ref": "InitialInvestment",
"Value": [
[
{
"Value": "52000"
}
]
]
}
],
"Outputs": [
"scen2CleanShare"
],
"GoalSeek": {
"Enabled": true,
"TargetRef": "oMacroSc21",
"ChangingRef": "scen2CleanShare",
"TargetValue": 0,
"MaxIterations": 1000,
"MaxChange": 0.000001
},
"ApplicationKey": "b2078bc678b94f40b6a5793009e56594"
}
Response
|
Property Name |
Type |
Description |
|---|---|---|
| Success | Boolean | Indicated whether or not the request was successful |
| InvalidToken | Boolean | If the request is unsuccessful, indicates whether or not the failure was due to token. |
| Messages | Array of String | A list of messages, which can be used or captured for diagnostics. When requests are unsuccessful, the reason for the failure will be documented in the Messages list. |
| Message | String | When requests are unsuccessful due to calculation engine, the response of the core calculation engine will be documented here. |
| GoalSeek | Object | Contains the results of the goal seek calculation. Object properties can be found below. |
| Outputs | Array of Object
JSON Schema: single cell: { Value: [ [ { Value: “10” } ] ] } |
Collection of cells or references that are requested from the server.
The property name will correspond to a cell reference (e.g. WorksheetA!$A$4) or a named range. |
GoalSeek (Output) Members
|
Property Name |
Type |
Description |
|---|---|---|
| Success | Boolean | Indicated whether or not the goal seek calculation is successful.
If false, other fields will be empty. |
| ChangingFormat | String | Contains the format string of the Changing Cell after the goal seek calculation.
|
| ChangingValue | String | Contains the formatted string of the Changing Cell after the goal seek calculation.
|
| TargetFormat | String | Contains the format string of the Target Cell after the goal seek calculation.
|
| TargetText | String | Contains the formatted string of the Target Cell after the goal seek calculation.
|
| TargetValue | String | Contains the exact value of the Target Cell after the goal seek calculation.
|
Response Sample (Simple)
Headers
HTTP/1.1 200 OK Cache-Control: no-cache, no-store Content-Type: application/json; charset=utf-8
Body(formatted)
{
"Message": null,
"GoalSeek": null,
"Outputs": [
{
"Ref": "SumOfInputs",
"Value": [
[
{
"Type": "Number",
"Value": "300",
"Format": "General",
"Text": "300"
}
]
]
},
{
"Ref": "ProductOfInputs",
"Value": [
[
{
"Type": "Number",
"Value": "20000",
"Format": "General",
"Text": "20000"
}
]
]
}
],
"Success": true,
"InvalidToken": false,
"Messages": []
}
Responsive Sample (Save)
Header:
HTTP/1.1 200 OK Cache-Control: no-cache, no-store Content-Type: application/json; charset=utf-8
Body:
{
"Message": null,
"GoalSeek": null,
"Outputs": [
{
"Ref": "OutputA",
"Value": [
[
{
"Type": "Number",
"Value": "16",
"Format": "General",
"Text": "16"
}
]
]
},
{
"Ref": "SpreadsheetWebRecordId",
"Value": [
[
{
"Type": null,
"Value": "8",
"Format": null,
"Text": null
}
]
]
}
],
"Success": true,
"InvalidToken": false,
"Messages": []
}
Response Sample (GoalSeek)
Headers:
HTTP/1.1 200 OK Cache-Control: no-cache, no-store Content-Type: application/json; charset=utf-8
Body (formatted):
{
"Message": null,
"GoalSeek": {
"Success": true,
"ChangingFormat": "0.00%",
"ChangingValue": "0.0127889680496421",
"TargetFormat": "\"$\"#,##0",
"TargetText": "$0",
"TargetValue": "-8.45728209242225E-07"
},
"Outputs": [
{
"Ref": "scen2CleanShare",
"Value": [
[
{
"Type": "Number",
"Value": "0.0127889680496421",
"Format": "0.00%",
"Text": "1.28%"
}
]
]
}
],
"Success": true,
"InvalidToken": false,
"Messages": []
}