Session¶
Definition¶
Extends¶
Extended By¶
None
Description¶
Represents the session for this user's login. There is a global variable 'session' that implements a Session instance and can be used for accessing session level objects such as properties, panels, datamodels, etc.
Method Summary¶
| Owner | Name | Return Type | Description |
|---|---|---|---|
| Session | agentStatus(runId) | Map | Returns a map describing an agent run: found, runId, done, cancelled, result, stopReason, iterationCapped, wallClockCapped, messages, error. An unknown id returns found=false rather than null, so a caller never has to distinguish 'no such run' from 'AI disabled'. While done=false the result is null and messages grows as the run works. Only the most recent runs of this session are tracked; a very old id may have been evicted. |
| Session | alert(alertText, closeButtonTextAndTitleText) | String | Shows alert dialog with given text. The second and third arguments are optional. Returns null. |
| Session | callCommand(appId or loginId, commandId, table) | String | Calls a command (asynchronously) and returns the command uid. If the command has no route, then null is returned. See callback Layout::onAsyncCommandResponse(...) for processing the response once it's available. WARNING: If multiple commands are registered under the same appId and commandId then it will call the first |
| Session | callCommand(appId or loginId, commandId, table, timeoutMillis) | String | Calls a command (asynchronously) and returns the command uid. If the command has no route, then null is returned. See callback Layout::onAsyncCommandResponse(...) for processing the response once it's available. |
| Session | callCommandSync(appId or loginId, commandId, table) | CommandResponse | Calls a command synchronously, meaning do not continue execution of script until the command completes. |
| Session | callCommandSync(appId or loginId, commandId, table, timeoutMillis) | CommandResponse | Calls a command synchronously with a specified timeout, meaning do not continue execution of script until the command completes. |
| Session | callRpcSync(rpcRequest) | RpcResponse | Sends a request to a remote instanceof of AMI using CORS. |
| Session | cancelAgent(runId) | Boolean | Asks an agent run to stop, aborting its in-flight provider call. Returns false if the id is unknown. The run finishes with stopReason CANCELLED and whatever it had produced so far is still readable via agentStatus(). |
| DashboardResource | commit() | Object | Commits transient changes, promoting overrides to persisted values. If transient, makes permanent. |
| Session | copyToClipboard(text) | String | Copies text to clipboard - returns result of copy |
| Session | deleteDatamodel(dmName) | Boolean | Deletes a transient datamodel. Returns true on success, otherwise returns false. Target datamodel must be transient and must not be a dependency of other datamodels. |
| Session | deleteSavedAgentRun(runId) | Boolean | Deletes one saved run context, so a later resume of that runId will no longer find it. Returns false when this user has nothing stored under that id. Does not touch a live run -- use cancelAgent(runId) for that -- and does not touch saved chat conversations. |
| Session | downloadToBrowser(fileName, fileData) | Boolean | Returns true if able to download file to browser, false otherwise. |
| Session | downloadToBrowser(fileName, fileData) | Boolean | Returns true if able to download file to browser, false otherwise. |
| Session | exec(when, amiScript) | Object | Runs script deferred. The provided script is compiled in current thread, but executed outside this call. If provided time is in the past, then the script will be executed at the earliest opportunity. This always runs on the root layout, we recommend using layout.exec(...) instead. |
| Session | exportLayout() | Map | Exports the current layout to a map. |
| Session | getBrowserIp() | String | Returns the current browser ip. |
| Session | getBrowserTitle() | String | Returns the title shown in the browser title bar. |
| Session | getBrowserZoom() | Double | Returns the Browser Zoom (1 = 100%) |
| DashboardResource | getCallback(callbackName) | Callback | Returns a callback by name |
| DashboardResource | getCallbackNames() | List | Returns the callback names defined for this dashboard resource. Use session.getDevTools().getCallbackEditor(resource, callbackName) to edit one, and call editor.open() when you want to show the UI. |
| DashboardResource | getCallbacks() | Map | Returns a map of all callback definitions. |
| DashboardResource | getChildren() | List | Returns a list of the child dashboard resources. |
| Object | getClassName() | String | Returns the string name of this object's class type. |
| Session | getColorMode() | String | Returns the id of the currently active color mode, or null if none is set. |
| Session | getColorModes() | List | Returns the list of available color mode ids for the active styleset, in declaration order. |
| Session | getCustomPreference(customPreferenceId) | Object | Returns a custom prefernce, or null if no custom preference exists for the id. |
| Session | getCustomPreferenceIds() | Set | Returns a set of the existing custom preferences ids. |
| DashboardResource | getDRI() | String | Returns the Dashboard Resource Indicator (DRI) as a string. DRI is the unique identifier of an object within the entire dashboard. |
| Session | getDashboardResource(dri) | DashboardResource | Return the dashboard resource for the given DRI, see DashboardResource::getDRI(). Returns null if no such resource exists. |
| DashboardResource | getDashboardResourceType() | String | Returns the Dashboard Resource Type as a string |
| Session | getDashboardResources() | List | Return all currently managed dashboard resources. Use getDRI(), getDashboardResourceType(), and getDashboardResourceSubtype() on each item to inspect valid DRIs. |
| Session | getDashboardStyleSet() | StyleSet | Returns the StyleSet for this panel. |
| Session | getDatamodels() | List | Returns all datamodels. |
| Session | getDesktopLocation() | Rectangle | Returns the location of the desktop, upper left is always zero, the width and height reflect the browser size (minus window border). |
| Session | getDevTools() | DevTools | Returns the dev tools for this session, or null if account is a non-dev user. |
| Session | getFileSystem() | FileSystem | Returns a FileSystem object for accessing the file system that amiweb is running on. |
| DashboardResource | getFormula(formulaName) | Formula | Returns a Formula given the formula name. |
| DashboardResource | getFormulaNames() | Set | Returns a set of the names of all formulas for this object. |
| DashboardResource | getFormulas() | Map | Returns a map of all available formulas for this object. The key is the formula name. |
| Session | getGlobalProperty(key) | String | Returns the value associated with key from this servers properties, for example a property set in root.properties file. Returns null if property does not exist. |
| Session | getHostIp() | String | Returns the current host ip of the remote connection known by the ami web server. |
| DashboardResource | getLRI() | String | Returns the Localized Resource Indicator (LRI) as a string. LRI is the unique identifier of this resource with the parent element. |
| Session | getLabel() | String | Returns the label associated with this session. The label is visible in the 3forge_session page |
| Session | getLoginId() | String | Returns the current sessionid. |
| DashboardResource | getOwner() | DashboardResource | Returns the DashboardResource that owns this object. |
| Session | getPanels() | List | Returns all AMI panels. |
| Session | getProperty(key) | String | Returns value associated with key from this session's global properties. Returns null if key does not exist. |
| Session | getRelationship(relationshipId) | Relationship | Returns the relationship for the given alias.relationshipId, or null if there is no relationship with the given id. |
| Session | getRelationships() | List | Returns a list of all relationships. |
| Session | getRootLayout() | Layout | Returns root layout for this dashboard. |
| Session | getSessionId() | String | Returns the current sessionid. |
| Session | getSsoSession() | SsoSession | Returns the sso session associated with this user session. |
| Session | getStyleSet(styleSetId) | StyleSet | Returns the styleset for a given id. |
| Session | getStyleSetIds() | Set | Return set of ids for all defined stylesets, including ids for predefined styles. |
| Session | getStyleSets() | List | Returns a list of all stylesets, including predefined ones. |
| Session | getTimeZone() | String | Returns the user's timezone Identifier, same as the global reserved variable __TIMEZONE. |
| Session | getToken() | String | Returns the unique token for this session, same as the global reserved variable __TOKEN. |
| Session | getTransientIdPrefix() | String | Returns the transient id prefix |
| Session | getUrl() | String | Returns the url. |
| Session | getUrlParams() | Map | Returns all AMI windows as a map of ami alias dot panel id to window. |
| Session | getUserPreferencesNamespace() | String | Returns the user preferences namespace set on this dashboard. |
| Session | getUsername() | String | Returns the current username, which is the name used to login. |
| Session | getValue(key) | Object | Returns the value associated with key from this sessions attributes. Returns null if key does not exist. |
| Session | getValues() | Map | Returns a map of the values from this sessions attributes. Note, modifying the returned map will have no effect on the sessions variables. |
| Session | getWindows() | List | Returns all AMI windows as a list. |
| Session | getWindowsMap() | Map | Returns all AMI windows as a map of ami alias dot panel id to window. |
| Session | importDatamodel(dmConfig) | Datamodel | Imports a datamodel. Will run the datamodel if web is connected to the center. |
| Session | importRelationship(config) | Relationship | Imports a relationship from a configuration map. Returns the new Relationship. |
| Session | importWindow(windowName, panelConfig) | Boolean | Imports a new Window. |
| DashboardResource | invokeCallback(callbackName, args) | Object | Executes the specified callback definition and returns the result from the callback. |
| Session | isFeedSnapshotProcessed(type) | Boolean | Returns true if the snapshot has been processed from ALL centers for the supplied type. |
| Session | isHttpsConnection() | Boolean | Returns true if the browser is connected over https (instead of http). |
| DashboardResource | isTransient() | Boolean | Returns true if this is transient, false otherwise. Transient objects are not saved to the layout. |
| Session | loadLayout(layoutName, layoutConfig) | Boolean | Loads a layout from a json configuration, see exportConfig(). |
| Session | loadUserPreferences(userPreferences) | String | Loads the user preferences. |
| Session | loadUserPreferences() | Boolean | Loads the user preferences. Same as Account > Load Preferences. Returns false if User Namespace is not set |
| Session | log(message, additionalMessages) | String | Logs user description followed by dash dash and then a concatenation of supplied arguments to AMISCRIPT logger. Returns message logged. |
| Session | logout() | String | Ends this users session and logs the user out of all sessions. NOTE: If user is a developer, then follows Account -> My Developer Settings -> On Automated Logout settings. |
| Session | notify(title, body, imageurl, options, attachment) | String | Displays a notification to the user in the task tray. When the user clicks on the notification the Layout::onNotificationHandled(...) is called. Returns a unique id representing the notification. |
| Session | now() | UTC | Depricated. Use new UTC(). Returns the current time in milliseconds since unix epoch. |
| Session | nowNano() | UTCN | Depricated. Use new UTCN(). Returns the current time in nanoseconds since unix epoch. |
| Session | openWindowURL(url, percentSizeOfMainWndow, windowName, customFeatures) | Object | Opens a new Window with the url, size, name, and custom features specified. |
| Session | playAudio(audiourl) | Object | Plays audio, specified by the url. |
| Session | prompt(alertText, title, buttons) | String | Shows a dialog with given text and title, along with a list of buttons to choose from. Return blocks until user chooses a button, returns whichever button was pressed, or null if the user closed the dialog. |
| Session | promptAi(provider, model, options, data, prompt) | String | Sends a prompt to an AI provider and returns the response text. (See ami.web.ai.enabled=true). Data is serialised to JSON and appended to the prompt. |
| Session | putCustomPreference(customPreferenceId, PreferencesOrNull) | Object | Sets the custom preferences by id, if preferencesOrNull is null then existing preferences are removed. |
| Session | runAgent(provider, model, options, prompt) | String | Starts an AI agent and returns a run id immediately -- it does NOT wait for the answer. Poll agentStatus(runId) for the result, or cancelAgent(runId) to stop it. Uses the same agent definitions as the chat: options.agent names one (default "Default"), and that file supplies both the system prompt and the tool allowlist. Returns null if AI is disabled (ami.web.ai.enabled=false). Unlike promptAi, which is a single request/response, this drives the full agent loop -- the model may think across several iterations before answering. The agent has the session's registered tools, narrowed by the named agent's front-matter allowlist and by options.tools. Stops after options.max_iterations iterations (default 50) and says so in the answer if it does. The run is attributed to the calling session's user. This call never blocks, by design. An AMIScript method holds the session's partition write lock, and every web tool an agent calls needs that same lock -- so a caller that waited here would hold the one thing the agent needs and every tool call would fail on lock timeout. Use promptAi when you want an answer inline. The api_key is taken from the server's ami.web.ai.<provider>.api_key config -- never passed in script. |
| Session | saveUserPreferences() | Boolean | Saves the user preferences. Same as Account > Save Preferences. Returns false if User Namespace is not set |
| Session | savedAgentRuns() | List | Lists the run contexts this user has saved, newest first: one map per context with runId, savedMs and bytes. A context is written only by a runAgent() call that asked to persist, and is what resume takes as its starting point. Nothing removes these on its own -- not a restart, not age -- so this is how you see what is being kept and deleteSavedAgentRun(runId) is how you get rid of one you are done with. |
| Session | sendEmail(fromAddress, toAddresses, subject, isHtml, body, attachmentNames, attachmentDatas, optionalUsername, optionalPassword) | String | Sends an email and returns immediately with the email-send-UID. |
| Session | sendEmail(fromAddress, toAddresses, subject, isHtml, body, attachmentNames, attachmentDatas, optionalUsername, optionalPassword, optionalRelayId) | String | Sends an email and returns immediately with the email-send-UID. |
| Session | sendEmailSync(fromAddress, toAddresses, subject, isHtml, body, attachmentNames, attachmentDatas, optionalUsername, optionalPassword) | String | Sends an email and returns with the email result. |
| Session | sendEmailSync(fromAddress, toAddresses, subject, isHtml, body, attachmentNames, attachmentDatas, optionalUsername, optionalPassword, optionalRelayId) | String | Sends an email and returns with the email result. |
| Session | setBrowserTitle(title) | Object | Sets the title shown in the browser title bar. If supplied title is null or blank, sets back to default. |
| Session | setColorMode(colorModeId) | Object | Sets the active color mode by id. The id must match one of the values returned by getColorModes(). |
| Session | setLabel(label) | Object | Set the label associated with this session. The label is visible in the 3forge_session page |
| Session | setUrlParams(url_params) | Object | Rewrite the browser's current URL parameters. Note, the LAYOUT param can NOT be modifed using this method and will be ignored if supplied. Also, this will not cause the onUrlParams callback to be fired |
| Session | setValue(key, value) | Boolean | Sets the key value pair to this session's attributes and returns true if successful. |
| Object | toJson() | String | Returns a string of a json representation of this object. |
| Session | warn(message, additionalMessages) | String | Logs at warning level the user description followed by dash dash and then a concatenation of supplied arguments to AMISCRIPT logger. Returns message logged. |
Method Definitions¶
agentStatus(runId)¶
Map Session::agentStatus(String runId)
Description¶
Returns a map describing an agent run: found, runId, done, cancelled, result, stopReason, iterationCapped, wallClockCapped, messages, error. An unknown id returns found=false rather than null, so a caller never has to distinguish 'no such run' from 'AI disabled'. While done=false the result is null and messages grows as the run works. Only the most recent runs of this session are tracked; a very old id may have been evicted.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| runId | String | The run id returned by runAgent() |
alert(alertText,closeButtonTextAndTitleText)¶
String Session::alert(Object alertText, Object ... closeButtonTextAndTitleText)
Description¶
Shows alert dialog with given text. The second and third arguments are optional. Returns null.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| alertText | Object | The text content of the alert |
| closeButtonTextAndTitleText | Object ... | the text for the close button. Defaults to "Close". the text for the title (top left). Defaults to "MESSAGE". |
callCommand(appId or loginId,commandId,table)¶
String Session::callCommand(String appId or loginId, String commandId, Table table)
Description¶
Calls a command (asynchronously) and returns the command uid. If the command has no route, then null is returned. See callback Layout::onAsyncCommandResponse(...) for processing the response once it's available. WARNING: If multiple commands are registered under the same appId and commandId then it will call the first
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| appId or loginId | String | can use loginId in AmiClient |
| commandId | String | |
| table | Table |
callCommand(appId or loginId,commandId,table,timeoutMillis)¶
String Session::callCommand(String appId or loginId, String commandId, Table table, Number timeoutMillis)
Description¶
Calls a command (asynchronously) and returns the command uid. If the command has no route, then null is returned. See callback Layout::onAsyncCommandResponse(...) for processing the response once it's available.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| appId or loginId | String | can use loginId in AmiClient |
| commandId | String | |
| table | Table | |
| timeoutMillis | Number |
callCommandSync(appId or loginId,commandId,table)¶
CommandResponse Session::callCommandSync(String appId or loginId, String commandId, Table table)
Description¶
Calls a command synchronously, meaning do not continue execution of script until the command completes.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| appId or loginId | String | can use loginId in AmiClient |
| commandId | String | |
| table | Table |
callCommandSync(appId or loginId,commandId,table,timeoutMillis)¶
CommandResponse Session::callCommandSync(String appId or loginId, String commandId, Table table, Number timeoutMillis)
Description¶
Calls a command synchronously with a specified timeout, meaning do not continue execution of script until the command completes.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| appId or loginId | String | can use loginId in AmiClient |
| commandId | String | |
| table | Table | |
| timeoutMillis | Number |
callRpcSync(rpcRequest)¶
RpcResponse Session::callRpcSync(RpcRequest rpcRequest)
Description¶
Sends a request to a remote instanceof of AMI using CORS.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| rpcRequest | RpcRequest |
cancelAgent(runId)¶
Boolean Session::cancelAgent(String runId)
Description¶
Asks an agent run to stop, aborting its in-flight provider call. Returns false if the id is unknown. The run finishes with stopReason CANCELLED and whatever it had produced so far is still readable via agentStatus().
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| runId | String | The run id returned by runAgent() |
commit()¶
Object DashboardResource::commit()
Description¶
Commits transient changes, promoting overrides to persisted values. If transient, makes permanent.
copyToClipboard(text)¶
String Session::copyToClipboard(String text)
Description¶
Copies text to clipboard - returns result of copy
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| text | String |
deleteDatamodel(dmName)¶
Boolean Session::deleteDatamodel(String dmName)
Description¶
Deletes a transient datamodel. Returns true on success, otherwise returns false.
Target datamodel must be transient and must not be a dependency of other datamodels.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| dmName | String |
deleteSavedAgentRun(runId)¶
Boolean Session::deleteSavedAgentRun(String runId)
Description¶
Deletes one saved run context, so a later resume of that runId will no longer find it. Returns false when this user has nothing stored under that id. Does not touch a live run -- use cancelAgent(runId) for that -- and does not touch saved chat conversations.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| runId | String | A runId from savedAgentRuns() |
downloadToBrowser(fileName,fileData)¶
Boolean Session::downloadToBrowser(String fileName, Binary fileData)
Description¶
Returns true if able to download file to browser, false otherwise.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| fileName | String | the name of the file |
| fileData | Binary | the content of the file |
downloadToBrowser(fileName,fileData)¶
Boolean Session::downloadToBrowser(String fileName, String fileData)
Description¶
Returns true if able to download file to browser, false otherwise.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| fileName | String | the name of the file |
| fileData | String | the content of the file |
exec(when,amiScript)¶
Object Session::exec(Number when, String amiScript)
Description¶
Runs script deferred. The provided script is compiled in current thread, but executed outside this call. If provided time is in the past, then the script will be executed at the earliest opportunity. This always runs on the root layout, we recommend using layout.exec(...) instead.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| when | Number | time - negative number is milliseconds in the future from now, zero or positive number is absolute time in millis. |
| amiScript | String | Script to execute |
exportLayout()¶
Description¶
Exports the current layout to a map.
getBrowserIp()¶
String Session::getBrowserIp()
Description¶
Returns the current browser ip.
getBrowserTitle()¶
String Session::getBrowserTitle()
Description¶
Returns the title shown in the browser title bar.
getBrowserZoom()¶
Double Session::getBrowserZoom()
Description¶
Returns the Browser Zoom (1 = 100%)
getCallback(callbackName)¶
Callback DashboardResource::getCallback(String callbackName)
Description¶
Returns a callback by name
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| callbackName | String | method name of callback |
getCallbackNames()¶
List DashboardResource::getCallbackNames()
Description¶
Returns the callback names defined for this dashboard resource. Use session.getDevTools().getCallbackEditor(resource, callbackName) to edit one, and call editor.open() when you want to show the UI.
getCallbacks()¶
Map DashboardResource::getCallbacks()
Description¶
Returns a map of all callback definitions.
getChildren()¶
List DashboardResource::getChildren()
Description¶
Returns a list of the child dashboard resources.
getClassName()¶
Description¶
Returns the string name of this object's class type.
getColorMode()¶
String Session::getColorMode()
Description¶
Returns the id of the currently active color mode, or null if none is set.
getColorModes()¶
Description¶
Returns the list of available color mode ids for the active styleset, in declaration order.
getCustomPreference(customPreferenceId)¶
Object Session::getCustomPreference(String customPreferenceId)
Description¶
Returns a custom prefernce, or null if no custom preference exists for the id.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| customPreferenceId | String |
getCustomPreferenceIds()¶
Set Session::getCustomPreferenceIds()
Description¶
Returns a set of the existing custom preferences ids.
getDRI()¶
String DashboardResource::getDRI()
Description¶
Returns the Dashboard Resource Indicator (DRI) as a string. DRI is the unique identifier of an object within the entire dashboard.
getDashboardResource(dri)¶
DashboardResource Session::getDashboardResource(String dri)
Description¶
Return the dashboard resource for the given DRI, see DashboardResource::getDRI(). Returns null if no such resource exists.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| dri | String | Dashboard Resource Indicator (the value returned by DashboardResource::getDRI()) |
getDashboardResourceType()¶
String DashboardResource::getDashboardResourceType()
Description¶
Returns the Dashboard Resource Type as a string
getDashboardResources()¶
List Session::getDashboardResources()
Description¶
Return all currently managed dashboard resources. Use getDRI(), getDashboardResourceType(), and getDashboardResourceSubtype() on each item to inspect valid DRIs.
getDashboardStyleSet()¶
StyleSet Session::getDashboardStyleSet()
Description¶
Returns the StyleSet for this panel.
getDatamodels()¶
Description¶
Returns all datamodels.
getDesktopLocation()¶
Rectangle Session::getDesktopLocation()
Description¶
Returns the location of the desktop, upper left is always zero, the width and height reflect the browser size (minus window border).
getDevTools()¶
DevTools Session::getDevTools()
Description¶
Returns the dev tools for this session, or null if account is a non-dev user.
getFileSystem()¶
FileSystem Session::getFileSystem()
Description¶
Returns a FileSystem object for accessing the file system that amiweb is running on.
getFormula(formulaName)¶
Formula DashboardResource::getFormula(String formulaName)
Description¶
Returns a Formula given the formula name.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| formulaName | String | name of the formula to return |
getFormulaNames()¶
Set DashboardResource::getFormulaNames()
Description¶
Returns a set of the names of all formulas for this object.
getFormulas()¶
Map DashboardResource::getFormulas()
Description¶
Returns a map of all available formulas for this object. The key is the formula name.
getGlobalProperty(key)¶
String Session::getGlobalProperty(String key)
Description¶
Returns the value associated with key from this servers properties, for example a property set in root.properties file. Returns null if property does not exist.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| key | String |
getHostIp()¶
Description¶
Returns the current host ip of the remote connection known by the ami web server.
getLRI()¶
String DashboardResource::getLRI()
Description¶
Returns the Localized Resource Indicator (LRI) as a string. LRI is the unique identifier of this resource with the parent element.
getLabel()¶
Description¶
Returns the label associated with this session. The label is visible in the 3forge_session page
getLoginId()¶
Description¶
Returns the current sessionid.
getOwner()¶
DashboardResource DashboardResource::getOwner()
Description¶
Returns the DashboardResource that owns this object.
getPanels()¶
Description¶
Returns all AMI panels.
getProperty(key)¶
String Session::getProperty(String key)
Description¶
Returns value associated with key from this session's global properties. Returns null if key does not exist.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| key | String |
getRelationship(relationshipId)¶
Relationship Session::getRelationship(String relationshipId)
Description¶
Returns the relationship for the given alias.relationshipId, or null if there is no relationship with the given id.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| relationshipId | String | id of the relationship |
getRelationships()¶
List Session::getRelationships()
Description¶
Returns a list of all relationships.
getRootLayout()¶
Layout Session::getRootLayout()
Description¶
Returns root layout for this dashboard.
getSessionId()¶
String Session::getSessionId()
Description¶
Returns the current sessionid.
getSsoSession()¶
SsoSession Session::getSsoSession()
Description¶
Returns the sso session associated with this user session.
getStyleSet(styleSetId)¶
StyleSet Session::getStyleSet(String styleSetId)
Description¶
Returns the styleset for a given id.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| styleSetId | String | Id of the styleSet to return |
getStyleSetIds()¶
Description¶
Return set of ids for all defined stylesets, including ids for predefined styles.
getStyleSets()¶
Description¶
Returns a list of all stylesets, including predefined ones.
getTimeZone()¶
Description¶
Returns the user's timezone Identifier, same as the global reserved variable __TIMEZONE.
getToken()¶
Description¶
Returns the unique token for this session, same as the global reserved variable __TOKEN.
getTransientIdPrefix()¶
String Session::getTransientIdPrefix()
Description¶
Returns the transient id prefix
getUrl()¶
Description¶
Returns the url.
getUrlParams()¶
Description¶
Returns all AMI windows as a map of ami alias dot panel id to window.
getUserPreferencesNamespace()¶
String Session::getUserPreferencesNamespace()
Description¶
Returns the user preferences namespace set on this dashboard.
getUsername()¶
Description¶
Returns the current username, which is the name used to login.
getValue(key)¶
Object Session::getValue(String key)
Description¶
Returns the value associated with key from this sessions attributes. Returns null if key does not exist.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| key | String |
getValues()¶
Description¶
Returns a map of the values from this sessions attributes. Note, modifying the returned map will have no effect on the sessions variables.
getWindows()¶
Description¶
Returns all AMI windows as a list.
getWindowsMap()¶
Description¶
Returns all AMI windows as a map of ami alias dot panel id to window.
importDatamodel(dmConfig)¶
Datamodel Session::importDatamodel(Map dmConfig)
Description¶
Imports a datamodel. Will run the datamodel if web is connected to the center.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| dmConfig | Map |
importRelationship(config)¶
Relationship Session::importRelationship(Map config)
Description¶
Imports a relationship from a configuration map. Returns the new Relationship.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| config | Map | Relationship configuration map, e.g. from Relationship::exportConfig() |
importWindow(windowName,panelConfig)¶
Boolean Session::importWindow(String windowName, Map panelConfig)
Description¶
Imports a new Window.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| windowName | String | |
| panelConfig | Map |
invokeCallback(callbackName,args)¶
Object DashboardResource::invokeCallback(String callbackName, Object ... args)
Description¶
Executes the specified callback definition and returns the result from the callback.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| callbackName | String | method name of callback |
| args | Object ... | arguments |
isFeedSnapshotProcessed(type)¶
Boolean Session::isFeedSnapshotProcessed(String type)
Description¶
Returns true if the snapshot has been processed from ALL centers for the supplied type.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| type | String | type, aka Table name |
isHttpsConnection()¶
Boolean Session::isHttpsConnection()
Description¶
Returns true if the browser is connected over https (instead of http).
isTransient()¶
Boolean DashboardResource::isTransient()
Description¶
Returns true if this is transient, false otherwise. Transient objects are not saved to the layout.
loadLayout(layoutName,layoutConfig)¶
Boolean Session::loadLayout(String layoutName, Map layoutConfig)
Description¶
Loads a layout from a json configuration, see exportConfig().
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| layoutName | String | |
| layoutConfig | Map |
loadUserPreferences(userPreferences)¶
String Session::loadUserPreferences(String userPreferences)
Description¶
Loads the user preferences.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| userPreferences | String | user preferences. User preferences format follows the exported user preferences. |
loadUserPreferences()¶
Boolean Session::loadUserPreferences()
Description¶
Loads the user preferences. Same as Account > Load Preferences. Returns false if User Namespace is not set
log(message,additionalMessages)¶
String Session::log(Object message, Object ... additionalMessages)
Description¶
Logs user description followed by dash dash and then a concatenation of supplied arguments to AMISCRIPT logger. Returns message logged.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| message | Object | |
| additionalMessages | Object ... |
logout()¶
Description¶
Ends this users session and logs the user out of all sessions. NOTE: If user is a developer, then follows Account -> My Developer Settings -> On Automated Logout settings.
notify(title,body,imageurl,options,attachment)¶
String Session::notify(String title, String body, String imageurl, Map options, Map attachment)
Description¶
Displays a notification to the user in the task tray. When the user clicks on the notification the Layout::onNotificationHandled(...) is called. Returns a unique id representing the notification.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| title | String | title of the notification |
| body | String | html body of the notification |
| imageurl | String | the url of the image (icon) |
| options | Map | options that get passed to the javascript Notification call, see Mozilla Notifications API for more information |
| attachment | Map | an attachment to be included in the callback (passed into 3rd param of Layout::onNotificationHandled) |
now()¶
Description¶
Depricated. Use new UTC(). Returns the current time in milliseconds since unix epoch.
nowNano()¶
Description¶
Depricated. Use new UTCN(). Returns the current time in nanoseconds since unix epoch.
openWindowURL(url,percentSizeOfMainWndow,windowName,customFeatures)¶
Object Session::openWindowURL(String url, Double percentSizeOfMainWndow, String windowName, String customFeatures)
Description¶
Opens a new Window with the url, size, name, and custom features specified.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| url | String | required url of target window |
| percentSizeOfMainWndow | Double | optional percentSizeOfWindow - valid values are 0.1 - 1.0, null creates new tab |
| windowName | String | optional name of window, _blank by default |
| customFeatures | String | optional windowFeatures - see javascript window.open |
playAudio(audiourl)¶
Object Session::playAudio(String audiourl)
Description¶
Plays audio, specified by the url.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| audiourl | String | the url of the audio clip to play |
prompt(alertText,title,buttons)¶
String Session::prompt(Object alertText, String title, List buttons)
Description¶
Shows a dialog with given text and title, along with a list of buttons to choose from. Return blocks until user chooses a button, returns whichever button was pressed, or null if the user closed the dialog.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| alertText | Object | |
| title | String | |
| buttons | List |
promptAi(provider,model,options,data,prompt)¶
String Session::promptAi(String provider, String model, Map options, List data, String prompt)
Description¶
Sends a prompt to an AI provider and returns the response text. (See ami.web.ai.enabled=true). Data is serialised to JSON and appended to the prompt.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| provider | String | AI provider id (e.g. "anthropic"); null/blank uses the configured default provider |
| model | String | Model id; null/blank uses the provider's configured default model |
| options | Map | Optional options map: "system" (system prompt String), "max_tokens" (Integer), "max_chars" (overall prompt char cap, default 200000; a non-positive value disables it). May be null |
| data | List | Optional List of result objects (Tables, TableSets, collections, maps, scalars) -- each is serialised to JSON and appended to the prompt; may be null |
| prompt | String | The instruction/prompt text |
putCustomPreference(customPreferenceId,PreferencesOrNull)¶
Object Session::putCustomPreference(String customPreferenceId, Object PreferencesOrNull)
Description¶
Sets the custom preferences by id, if preferencesOrNull is null then existing preferences are removed.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| customPreferenceId | String | |
| PreferencesOrNull | Object |
runAgent(provider,model,options,prompt)¶
String Session::runAgent(String provider, String model, Map options, String prompt)
Description¶
Starts an AI agent and returns a run id immediately -- it does NOT wait for the answer. Poll agentStatus(runId) for the result, or cancelAgent(runId) to stop it. Uses the same agent definitions as the chat: options.agent names one (default "Default"), and that file supplies both the system prompt and the tool allowlist. Returns null if AI is disabled (ami.web.ai.enabled=false). Unlike promptAi, which is a single request/response, this drives the full agent loop -- the model may think across several iterations before answering. The agent has the session's registered tools, narrowed by the named agent's front-matter allowlist and by options.tools. Stops after options.max_iterations iterations (default 50) and says so in the answer if it does. The run is attributed to the calling session's user. This call never blocks, by design. An AMIScript method holds the session's partition write lock, and every web tool an agent calls needs that same lock -- so a caller that waited here would hold the one thing the agent needs and every tool call would fail on lock timeout. Use promptAi when you want an answer inline. The api_key is taken from the server's ami.web.ai.<provider>.api_key config -- never passed in script.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| provider | String | AI provider id (e.g. "anthropic"); null/blank uses the configured default provider |
| model | String | Model id; null/blank uses the provider's configured default model |
| options | Map | Optional options map: "agent" (name of an agent definition, e.g. "Default" or "relay" -- supplies its system prompt and its front-matter tool allowlist), "system" (a raw system prompt, overriding the agent file), "tools" ("none", "*", or a List of tool names; default is every registered tool, narrowed by the agent's allowlist), "max_iterations" (Integer, default 50), "effort" (reasoning effort -- omit it to get the model's own default; a value the model does not support fails the run, so read the error from agentStatus), "persist" (Boolean -- keep this run's conversation when it ends so a later call can resume from it; default false), "resume" (a run id from an earlier persisted run -- the new prompt continues that conversation instead of starting a fresh one, and implies persist unless you set it false). May be null |
| prompt | String | The task for the agent to carry out |
saveUserPreferences()¶
Boolean Session::saveUserPreferences()
Description¶
Saves the user preferences. Same as Account > Save Preferences. Returns false if User Namespace is not set
savedAgentRuns()¶
List Session::savedAgentRuns()
Description¶
Lists the run contexts this user has saved, newest first: one map per context with runId, savedMs and bytes. A context is written only by a runAgent() call that asked to persist, and is what resume takes as its starting point. Nothing removes these on its own -- not a restart, not age -- so this is how you see what is being kept and deleteSavedAgentRun(runId) is how you get rid of one you are done with.
sendEmail(fromAddress,toAddresses,subject,isHtml,body,attachmentNames,attachmentDatas,optionalUsername,optionalPassword)¶
String Session::sendEmail(String fromAddress, List toAddresses, String subject, Boolean isHtml, String body, List attachmentNames, List attachmentDatas, String optionalUsername, String optionalPassword)
Description¶
Sends an email and returns immediately with the email-send-UID.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| fromAddress | String | From Address |
| toAddresses | List | List addresses to send email to |
| subject | String | Email Subject |
| isHtml | Boolean | true=email,false=text |
| body | String | Body |
| attachmentNames | List | Optional List of Attachment Names |
| attachmentDatas | List | Optional List of Attachment data, either Bytes or Strings |
| optionalUsername | String | Optional username to connect to smtp server with |
| optionalPassword | String | Optional password to connect o smtp server with |
sendEmail(fromAddress,toAddresses,subject,isHtml,body,attachmentNames,attachmentDatas,optionalUsername,optionalPassword,optionalRelayId)¶
String Session::sendEmail(String fromAddress, List toAddresses, String subject, Boolean isHtml, String body, List attachmentNames, List attachmentDatas, String optionalUsername, String optionalPassword, String optionalRelayId)
Description¶
Sends an email and returns immediately with the email-send-UID.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| fromAddress | String | From Address |
| toAddresses | List | List addresses to send email to |
| subject | String | Email Subject |
| isHtml | Boolean | true=email,false=text |
| body | String | Body |
| attachmentNames | List | Optional List of Attachment Names |
| attachmentDatas | List | Optional List of Attachment data, either Bytes or Strings |
| optionalUsername | String | Optional username to connect to smtp server with |
| optionalPassword | String | Optional password to connect o smtp server with |
| optionalRelayId | String | relayId of relay to use for sending email, use a comma delimited list to denote primary, secondary, etc |
sendEmailSync(fromAddress,toAddresses,subject,isHtml,body,attachmentNames,attachmentDatas,optionalUsername,optionalPassword)¶
String Session::sendEmailSync(String fromAddress, List toAddresses, String subject, Boolean isHtml, String body, List attachmentNames, List attachmentDatas, String optionalUsername, String optionalPassword)
Description¶
Sends an email and returns with the email result.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| fromAddress | String | From Address |
| toAddresses | List | List addresses to send email to |
| subject | String | Email Subject |
| isHtml | Boolean | true=email,false=text |
| body | String | Body |
| attachmentNames | List | Optional List of Attachment Names |
| attachmentDatas | List | Optional List of Attachment data, either Bytes or Strings |
| optionalUsername | String | Optional username to connect to smtp server with |
| optionalPassword | String | Optional password to connect o smtp server with |
sendEmailSync(fromAddress,toAddresses,subject,isHtml,body,attachmentNames,attachmentDatas,optionalUsername,optionalPassword,optionalRelayId)¶
String Session::sendEmailSync(String fromAddress, List toAddresses, String subject, Boolean isHtml, String body, List attachmentNames, List attachmentDatas, String optionalUsername, String optionalPassword, String optionalRelayId)
Description¶
Sends an email and returns with the email result.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| fromAddress | String | From Address |
| toAddresses | List | List addresses to send email to |
| subject | String | Email Subject |
| isHtml | Boolean | true=email,false=text |
| body | String | Body |
| attachmentNames | List | Optional List of Attachment Names |
| attachmentDatas | List | Optional List of Attachment data, either Bytes or Strings |
| optionalUsername | String | Optional username to connect to smtp server with |
| optionalPassword | String | Optional password to connect o smtp server with |
| optionalRelayId | String | relayId of relay to use for sending email, use a comma delimited list to denote primary, secondary, etc |
setBrowserTitle(title)¶
Object Session::setBrowserTitle(String title)
Description¶
Sets the title shown in the browser title bar. If supplied title is null or blank, sets back to default.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| title | String |
setColorMode(colorModeId)¶
Object Session::setColorMode(String colorModeId)
Description¶
Sets the active color mode by id. The id must match one of the values returned by getColorModes().
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| colorModeId | String | Id of the color mode to activate; pass null to clear. |
setLabel(label)¶
Object Session::setLabel(String label)
Description¶
Set the label associated with this session. The label is visible in the 3forge_session page
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| label | String | label for this session |
setUrlParams(url_params)¶
Object Session::setUrlParams(Map url_params)
Description¶
Rewrite the browser's current URL parameters. Note, the LAYOUT param can NOT be modifed using this method and will be ignored if supplied. Also, this will not cause the onUrlParams callback to be fired
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| url_params | Map | Url Parameters |
setValue(key,value)¶
Boolean Session::setValue(String key, Object value)
Description¶
Sets the key value pair to this session's attributes and returns true if successful.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| key | String | |
| value | Object |
toJson()¶
Description¶
Returns a string of a json representation of this object.
warn(message,additionalMessages)¶
String Session::warn(Object message, Object ... additionalMessages)
Description¶
Logs at warning level the user description followed by dash dash and then a concatenation of supplied arguments to AMISCRIPT logger. Returns message logged.
Parameter Definition¶
| Name | Type | Description |
|---|---|---|
| message | Object | |
| additionalMessages | Object ... |