Skip to main content

REST — Sessions

  • Updated

REST — Sessions

Sessions are the means by which REST persists changes through multiple API calls. A REST session allows for you to easily encapsulate a group of user-specific changes. Most REST changes will only affect the current session, with folder changes being the exception. However, once an API session is committed and Exago is launched, a user will be able to make such changes as their role permits.

light bulb

All requests require a Session Id URL parameter and basic request headers. In the following topic, headers are omitted in the interest of brevity.

Entering the API

A POST /Sessions call should always be the first made when entering the API. This creates a session, which contains a Session Id and an AppUrl.

Session Id

The Session Id is a GUID which uniquely identifies the instance of Exago you’re working in.

Example:

3c04c155-3317-4dab-a2ee-09572e3a8e44

This Id is passed as a URL parameter to all other method calls.

AppUrl

The AppUrl is a string that encodes the session information in a format readable by the host application.

Example:

ExagoHome.aspx?d=fk7hInneiNI7yUR1n8fCjjbTuIdTWgQrj8AaUlzO8l7K5JMaf7DhbZxzaSAXthP3bWLA%2fzG4AtXApO6pGoBpzQ%3d%3d&showerrordetail=true

The AppUrl consists of three components:

  • the Home Page,
  • an alphanumeric string,
  • and the ShowErrorDetail URL parameter.

Once you have committed API changes and want to launch Exago, append the AppUrl to the end of the Exago base URL and launch the full URL string in a browser:

http://yoursite.com/exago/ExagoHome.aspx?d=fk7hInneiNI7yUR1n8fCjjbTuIdTWgQrj8AaUlzO8l7K5JMaf7DhbZxzaSAXthP3bWLA%2fzG4AtXApO6pGoBpzQ%3d%3d&showerrordetail=true

An AppUrl can only be used once. Launching an API session permanently closes it, and applies customization to a new user session in the host application.

light bulb

Retrieving the AppUrl via GET /Sessions/{Id} should always be the last call made when finishing in the API if you didn’t store it after the initial POST /Sessions call.

Session JSON

The Sessions endpoint allows for creation and deletion of sessions and access to some general settings. It also allows you to specify and configure the action that the session will take when launched. To launch a report in the full user interface, it needs to be set in Sessions as the output report. Sessions are represented as JSON objects with the following properties:

Table A — Session JSON definition
NameTypeWritableDescription
IdstringnoThe unique Id of this session (“sid”)
AppUrlstringnoThe AppUrl of this session; changes to reflect any modifications made to this session in the API
Pagestringyes (“ExagoHome”)The Exago home page
ApiActionenumyes (“Default”)wrApiAction, to take when this session is launched
ExportTypeenumyeswrExportType, if ApiAction is ExecuteReport
ShowTabsBooleanyes (true)Whether the tab bar should be shown
ShowErrorDetailBooleanyes (true)Whether detailed error messages should be shown
ReportSettingsReport JSONyesA report with optional sorts & filters if ApiAction is ExecuteReport or EditReport
ApiKeystringnoUsed when instantiating the JavaScript API, if applicable.

Session JSON Example

{
   "AppUrl":"ExagoHome.aspx?d={alphanumeric}&showerrordetail=true",
   "Id":"{sid}""Page":"ExagoHome",
   "ApiAction":"ExecuteReport",
   "ExportType":"Html",
   "ShowTabs":true,
   "ShowErrorDetail":true,
   "..."
}

Report JSON

To edit or launch a report, specify a report in the Session object’s ReportSettings property. Reports are represented as JSON objects with the following properties:

Table B — Report JSON definition
NameTypeWritableDescription
Idstringyes (v2021.1+)
no (pre-v2021.1)		The unique ID of the this report
Can be used to retrieve a report from the Storage Management database in lieu of the ReportPath property below in v2021.1+
ReportPathstringyesFull path from root folder to this report
SortsResourceSorts JSONyesAny sorts to apply to this report
FilterItemsarray of Filter JSONyesAny filters to apply to this report
IsErrorBooleannoWhether there were any validation errors when loading this report
ErrorListarray of ReportValidationErrorTypenoIf IsError == true, a list of errors encountered when loading this report.

Example

"ReportSettings":{
   "Id":"ad0f442e-275b-48a0-893f-0b1255ee7880",
   "ReportPath":"ReportsProduct Sales Report",
   "SortsResource":null,
   "FilterItems":[
      
   ],
   "IsError":false,
   "ErrorList":null
}
light bulb

Windows file paths are delineated by double-backslashes: \\

Sorts JSON

Sorts can be added to the report either in addition to, or replacing existing sorts. This only affects the current session, and does not edit the base report. The collection of sorts to be added is represented as a JSON object with the following properties:

Table C — Sorts JSON definition
NameTypeWritableDescription
ReplaceFlagstringyes (false)Whether to replace all existing report sorts
SortItemsarray of Sort JSONyesList of sorts to apply to this report

Example

{
   "ReplaceFlag":false,
   "SortItems":[
      {
         "Id":"Products.ProductName",
         "Asc":false
      },
      {
         "Id":"Categories.CategoryName",
         "Asc":false
      }"..."
   ]
}

Sort JSON

Each sort in the SortItems property is represented as a JSON object with the following properties:

Table D — Sort definition
NameTypeWritableDescription
IdstringrequiredData field to sort on;
format: “EntityName.ColumnName”
AscBooleanyes (false)Whether sort direction is ascending
Example:
{
   "Id":"Products.ProductName",
   "Asc":false
}

Filter JSON

Filters can be added to the report in addition to existing filters. This only affects the current session, and does not edit the base report. Each filter to be added is represented as a JSON object with the following properties:

Table E — Filter JSON definition
NameTypeWritableDescription
NamestringrequiredData field to filter on;
format: “EntityName.ColumnName”
EntityNamestringyesEntity name to filter on (deprecated)
ColumnNamestringyesColumn name to filter on (deprecated)
DataTypeenumyes (“string”)DataType
Operatorenumyes (“EqualTo”)Filter Operator Type
Valuesarray of stringsyesValues to filter with
AndFlagBooleanyes (true)Whether this filter should be AND-ed with the next (versus OR-ed)
PromptBooleanyes (false)Whether this filter should prompt the user for a value (Advanced or Express Reports)
GroupWithNextBooleanyes (false)Whether this filter should be grouped with the next (Advanced or Express Reports)
light bulb

Filter values that are DateTime strings must be able to be parsed by the .NET method DateTime.Parse using the current thread culture.

Example

{
   "Name":"Categories.CategoryName",
   "DataType":"string",
   "Operator":"OneOf",
   "Values":[
      "Beverages",
      "Seafood",
      "Produce"
   ],
   "AndFlag":true,
   "Prompt":false,
   "GroupWithNext":false
}

Create a Session

POST /rest/Sessions

Available parameters

Table F — Parameters for creating a Session
NameTypeDescription
configstring

Specify which config file to create the session with.

Format: CustomConfigFile

Using curl

curl http://{webservice}/rest/Sessions -X POST ^
	-d "{'Page':'Reporting','ApiAction':'Home','ShowTabs':false}"

Example response

Status: 201 Created
Location: /{webservice}/rest/Sessions/{sid}

{
  "AppUrl": "Reporting.aspx?d={alphanumeric}",
  "Id":              "{sid}",
  "Page":            "Reporting",
  "ApiAction":       "Home",
  "ExportType":      null,
  "ShowTabs":        false,
  "ShowErrorDetail": true,
  "ReportSettings": {
    "ReportPath": null,
    "SortsResource": null,
    "FilterItems": null
  }
}
red exclamation point

Currently, if a new XML configuration file and temp path are passed via a POST session, the API session .enc file will first be written to the original temp path of the default config file rather than the newly assigned path. This limitation prevents this action from being properly completed. However, a new XML configuration file may still be passed with the default temp path, allowing this limitation to be bypassed.

Save a Session to Storage v2021.2+

Save the current session to persistent storage (for example WebReports.xml).

POST /rest/Sessions/Save/

Payload

NameTypeDescription
sidstringThe session ID (sid) of the session to save.
FileNamestringThe file name to save to. Required.

Example Payload

This example writes the current session (with session ID 4a9b1ca6-b2e3-4994-8f7d-8033f5f0d356) to a new file WebReports2.xml.

{
   "sid":"4a9b1ca6-b2e3-4994-8f7d-8033f5f0d356",
   "file name":"WebReports2.xml"
}
light bulb

When saving a session as part of a Batch REST request, only the FileName property in the payload is required. The current session ID will be used automatically.

For example:

{
    "Url": "Sessions/Save",
    "Method": "POST",
    "Payload": {
        "FileName" : "MyConfig.xml"
     }
  }

Using curl

curl http://{webservice}/rest/Sessions/Save -X POST ^
	-d "{'sid':'4a9b1ca6-b2e3-4994-8f7d-8033f5f0d356','FileName':'WebReports2.xml'}"

Example Response

204 No Content

Show a Session

If the session is launched, the session object is deleted and can no longer be viewed.

GET /rest/Sessions/{sid}
light bulb

Unlike other resources, the {sid} is passed as part of the endpoint string, not as a URL parameter.

Using curl

curl http://{webservice}/rest/Sessions/{sid} -X GET

Example response

Status: 200 OK

{
  "AppUrl": "Reporting.aspx?d={alphanumeric}",
  "Id":   "{sid}",
  "Page": "Reporting",
  ...
}

Edit a Session

Only supply the properties to be edited. If the session is launched, the session object is deleted and it can no longer be edited.

PATCH /rest/Sessions/{sid}
light bulb

Unlike other resources, the {sid} is passed as part of the endpoint string, not as a URL parameter.

Using curl

curl http://{webservice}/rest/Sessions/{sid} -X PATCH ^
	-d "{'Page':'CompanyHome'}"

Example response

Status: 200 OK

{
  "AppUrl": "Reporting.aspx?d={alphanumeric}",
  "Id":   "{sid}",
  "Page": "CompanyHome",
  ...
}

Delete a Session

If a session is deleted, the AppUrl can no longer be used. If the session is launched, the session object is deleted and it can no longer be edited.

DELETE /rest/Sessions/{sid}
light bulb

Unlike other resources, the {sid} is passed as part of the endpoint string, not as a URL parameter.

Using curl

curl http://{webservice}/rest/Sessions/{sid} -X DELETE

Example response

Status: 204 No Content

Launch a Report with Sorts and Filters

Set the ApiAction to ExecuteReport, and specify a report, with any optional sorts and filters, in the ReportSettings property. If you want to save the report to a file, set the ExportType to the desired file type.

POST /rest/Sessions

Using curl

curl http://{webservice}/rest/Sessions -X POST ^
	-d @sessionSettings.txt

sessionSettings.txt

{
   "ApiAction":"ExecuteReport",
   "ExportType":"html",
   "ReportSettings":{
      "ReportPath":"SalesProducts",
      "FilterItems":[
         {
            "Name":"Categories.CategoryID",
            "DataType":"Integer",
            "Values":[
               "123"
            ]
         }
      ],
      "SortsResource":{
         "ReplaceFlag":true,
         "SortItems":[
            {
               "Id":"Categories.CategoryID",
               "Asc":true
            }
         ]
      }
   }
}

Response

Status: 201 Created
Location: /{webservice}/rest/Sessions/{sid}

{
  ...
  "ApiAction":       "ExecuteReport",
  "ExportType":      "Html",
  ...
  "ReportSettings": {
    ...
    "ReportPath": "SalesProducts",
    "SortsResource": {
      "ReplaceFlag": true,
      "SortItems": [
        {
          "Id": "Categories.CategoryID",
          "Asc": true
        }
      ]
    },
    "FilterItems": [
      {
        "Name": "Categories.CategoryID",
        "DataType": "Integer",
        "Values": ["123"]
      }
    ]
  }
}

To launch the report in Exago, take the AppUrl, and append it to the URL to the Exago installation to create the full URI path:

http://{website}/{exago}/{AppUrl}

Example

http://yoursite.com/reporting/homepage?d={alphanumeric}&showerrordetail=true

Related articles