GetResult (Application-Level)

You are here:

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

ApplicationKeyStringRequiredThe application key, corresponding to your specific web service application. This constitutes the identifier for the requested resource.
InputsArray of Object

JSON Schema:

Setting a single cell:

{
Ref: “Sheet1!A5”,

Value: [

[

{

Value: “10”

}

]

]

}

RequiredCollection 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.

OutputsArray of String:

[

“CellE”,

“CellF”,

“CellG”

]

RequiredA 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.

GoalSeekObjectOptionalThe GoalSeek property contains input parameters required by the goal seek feature. The object’s properties can be found below.
SessionIdStringOptionalA session identifier, to be utilized in conjunction with the /OpenDedicatedSession and /CloseDedicatedSession methods. Details are outlined in the corresponding sections.
SaveInformationObjectOptionalThe 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

SaveBooleanRequiredWhether 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.

RecordIdInt?OptionalIf saving the record as an update (rather than a new record), this value should correspond to the underlying data record identifier.
SetRecordStatusIndexInt?OptionalIf 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.
SetGroupIdInt?OptionalIf 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.
SetAssignedUserNameStringOptionalIf saving the record – whether create or update – this parameter should indicate the user that this record should be assigned to.
UserNameStringOptional for Unrestricted Applications, Required for Restricted ApplicationsA 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

EnabledBooleanRequiredDetermines the execution of the goal seek algorithm during calculations. Setting this to TRUE will enable goal seek based on the other parameters.
TargetRefStringRequiredDetermines 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.

ChangingRefStringRequiredDetermines 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.

TargetValueDoubleRequiredTargetValue 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.
MaxIterationsIntOptionalMaximum 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.

MaxChangeDoubleOptionalThe 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
Body (formatted)
{
    "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

SuccessBooleanIndicated whether or not the request was successful
InvalidTokenBooleanIf the request is unsuccessful, indicates whether or not the failure was due to token.
MessagesArray of StringA 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.
MessageStringWhen requests are unsuccessful due to calculation engine, the response of the core calculation engine will be documented here.
GoalSeekObjectContains the results of the goal seek calculation. Object properties can be found below.
OutputsArray of Object

JSON Schema:

single cell:

{
Ref: “Sheet1!A5”,

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

SuccessBooleanIndicated whether or not the goal seek calculation is successful.

If false, other fields will be empty.

ChangingFormatStringContains the format string of the Changing Cell after the goal seek calculation.

 

ChangingValueStringContains the formatted string of the Changing Cell after the goal seek calculation.

 

TargetFormatStringContains the format string of the Target Cell after the goal seek calculation.

 

TargetTextStringContains the formatted string of the Target Cell after the goal seek calculation.

 

TargetValueStringContains 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": []
}