Class: ArchSession | Architect Scripting

new ArchSession()

A class that provides support for an Architect Scripting session. Architect Scripting will automatically create a singleton instance of this class that should be used by scripts. It is from this class instance that you will start the session and specify a runtime function for the session to run. When the runtime function completes its execution, it will then end the node process.

The process for running a script is the following:

Call ArchSession#startWithClientIdAndSecret or ArchSession#startWithAuthToken to start a session.
If successful, Architect Scripting will invoke the runtime function you specified in either of the start calls. If your script runtime function is called, it means you're successfully logged in.
Do whatever scripting work you wish to do in the runtime function. If the runtime function returns a promise, Architect Scripting will wait for the promise to resolve.
Architect Scripting will at that point call the appropriate end method based on the ArchSession#endMode that is set on the session.
You can specify the exit code that will be used by setting the or ArchSession#endExitCode property. Remember that the exit code of 99 is reserved for use by Architect Scripting.

When you start a session, you'll submit the organization location where you want this script to run. The location will is used to figure out the environment (dev, test, or prod), host uri and region for scripting calls. The locations of dev and test are reserved for internal use by Genesys.

Extends

ArchBaseObject

Members

static, readonly displayTypeName :string

Implements override support for the display type name string for this Architect Scripting object.

static, readonly isArchSession :boolean

Returns true indicating that this is an ArchSession instance.

readonly archSessionId :string

ID that represents the current script execution session. This ID is sent in all trace messages and can be used by Genesys Cloud Support to investigate specific log traces.

readonly authToken :string

The authorization token for this session. This will be available after one of the session start methods succeeds.

See:

endExitCode :number

The end exit code is an integer that will be supplied to the process exit when either ArchSession#end, ArchSession#endWithLogout or ArchSession#startWithClientIdAndSecret or ArchSession#startWithAuthToken completes execution. The exit code of 99 is reserved for use by Architect Scripting and will be set if there is an unhandled exception not caught in the runtime function or if there is a problem encountered prior to execution of the runtime function.

endMode :string

This property specifies how the session should end after starting. The string values in ArchEnums#SESSION_END_MODES lists valid values. The default is 'end'. This mode determines whether Scripting will call ArchSession#end or ArchSession#endWithLogout when ArchSession#startWithClientIdAndSecret or ArchSession#startWithAuthToken completes.

endTerminatesProcess :boolean

This property specifies whether or not the session ending will try and terminate the process in which this is running. If an end callback function is specified, it is called prior to processing this boolean to see if the process should exit. This property defaults to true unless there is no process or process.exit method available to the Architect Scripting runtime and then it will default to false. It is fine to set this property value prior to calling either the startWithClientIdAndSecret or startWithAuthToken methods to control session end behavior for startup failures such as the user or OAuth client associated with the client id and secret or authorization token not having the ui:architect:view permission which is required for Architect Scripting or other startup related issues.

readonly environment :string

The environment obtained from the session start location. The string values in ArchEnums#ENVIRONMENTS lists valid values.

See:

readonly host :string

The host uri obtained from the session start location.

See:

readonly isConnected :boolean

Returns whether or not the session is connected / authenticated.

readonly logStr :string

Returns a string suitable for logging.

Overrides:

ArchBaseObject#logStr

readonly logStrTypeOnly :string

This is a string suitable for logging information about this object where it's just the object's type. This is normally used when logging errors that occur in constructor parameter checking because the scripting object isn't set up and the normal logging str contents wouldn't be set up.

Inherited From:

ArchBaseObject#logStrTypeOnly

readonly orgId :string

The organization identifier for the currently connected session. If the session is not connected or Scripting is unable to load organization information, this property will return nothing. Please replace calls to this property by accessing the orgInfo property and then access the id property off of the returned organization information instance.

Deprecated:

readonly orgInfo :ArchOrganizationInfo

Organization information for this session.

readonly orgName :string

The organization name for the currently connected session. If the session is not connected or Scripting is unable to load organization information, this property will return nothing. Please replace calls to this property by accessing the orgInfo property and then access the name property off of the returned organization information instance.

Deprecated:

readonly region :string

The region obtained from the session start location.

See:

readonly status :string

Returns the status of this session. The string values in ArchEnums#SESSION_STATUSES lists valid status values.

Methods

end(processPendingAsyncWorkopt)

This function will end the current scripting session. It does not attempt to log the currently authenticated user out. If you wish to log the currently authenticated user out, see ArchSession#endWithLogout. This method performs the following functionality in this order:

1.  If the processPendingAsyncWork parameter is true, it processes any pending asynchronous work.
2.  If a session ending callback function was supplied on either the startWithClientIdAndSecret or startWithAuthToken
    start methods and the session ending callback function hasn't already been called, it invokes the session
    ending callback function.  It is possible that the session ending callback function was already
    called if endWithLogout was called and this end method is being called
    as the last part of endWithLogout's processing.
3.  Sets the session's status to ArchEnums.SESSION_STATUSES.ended.
4.  Looks to see if ending the session should terminate the process by checking the endTerminatesProcess property.
    If so, it exits the process with the exit code value in endExitCode.
    If not, execution continues and the promise created from either the startWithClientIdAndSecret or startWithAuthToken
    start methods is resolved.  If you have code that runs when the promise is resolved, remember that code
    can check the endExitCode property.

Parameters:

Name	Type	Attributes	Default	Description
`processPendingAsyncWork`	boolean	<optional>	false	whether or not to process all pending async work before ending.

endWithLogout(processPendingAsyncWorkopt)

This method is a wrapper around the ArchSession#end method that provides the additional functionality of logging out the currently authenticated user. It performs the following functionality in this order:

1.  If the processPendingAsyncWork parameter is true, it processes any pending asynchronous work.
2.  If a session ending callback function was supplied on either the startWithClientIdAndSecret or startWithAuthToken
    start methods, it invokes the session ending callback function.
3.  Logs out the currently authenticated user.
4.  Calls ArchSession#end.

Parameters:

Name	Type	Attributes	Default	Description
`processPendingAsyncWork`	boolean	<optional>	false	whether or not to process all pending async work before ending.

isFilterMatch(archFilterObject) → {boolean}

Returns whether or not this Architect Scripting object is a match for the supplied ArchFilterObject instance.

Parameters:

Name	Type	Description
`archFilterObject`	ArchFilterObject	the object filter to use to determine if it's a match.

Returns:

boolean

Inherited From:

ArchBaseObject#isFilterMatch

logError(errorStr)

Logs an error to the logging service with a log header from this object's logStr property value when ArchLogging#logErrors is true.

Parameters:

Name	Type	Description
`errorStr`	string	the error string to log.

Inherited From:

ArchBaseObject#logError

logErrorAndThrow(errorStr)

Logs an error to the logging service with a log header from this object's logStr property value when ArchLogging#logErrors is true and then throws the string in the errorStr parameter.

Parameters:

Name	Type	Description
`errorStr`	string	the error string to log. This should be a non-blank string.

Throws:

Throws the submitted error string.

Inherited From:

ArchBaseObject#logErrorAndThrow

logNote(noteStr)

Logs a note to the logging service with a log header from this object's logStr property value when ArchLogging#logNotes is true.

Parameters:

Name	Type	Description
`noteStr`	string	the note string to log. This should be a non-blank string.

Inherited From:

ArchBaseObject#logNote

logNoteVerbose(noteStr)

Logs a note to the logging service with a log header from this object's logStr property value when ArchLogging#logNotesVerbose is true.

Parameters:

Name	Type	Description
`noteStr`	string	the note string to log. This should be a non-blank string.

Inherited From:

ArchBaseObject#logNoteVerbose

logWarning(warningStr)

Logs a warning to the logging service with a log header from this object's logStr property value when ArchLogging#logWarnings is true.

Parameters:

Name	Type	Description
`warningStr`	string	the warning string to log. This should be a non-blank string.

Inherited From:

ArchBaseObject#logWarning

startWithAuthToken(orgLocation, callbackFunctionStart, authToken, callbackFunctionEndopt, isClientCredentialsOAuthClientopt) → {Promise}

This function starts an Architect Scripting session. You will need to specify the runtime location in which scripting session should run as well as an authorization token to use for authentication for the session. It is invalid to call this method when the session status is 'running'.

Parameters:

Name	Type	Attributes	Default	Description
`orgLocation`	string			the organization location to use for this session. The string values in `ArchEnums#LOCATIONS` lists valid location values.
`callbackFunctionStart`	callbackSessionStart			the function to call once authorized / logged in where you write code that does work. If a promise is returned from the callback function, the session will wait for the promise to resolve before ending.
`authToken`	string			the authorization token to use for authentication.
`callbackFunctionEnd`	callbackSessionEnd	<optional>		if specified, this function will be called when the session is about to end. If the session is configured to end and log out the currently logged in user, this method will be called prior to logging out the user. Any unhandled exceptions encountered during execution of the callback function will not change the exit code set on this session instance. We do not recommend returning a promise from this callback as the session's status will be set to `ended` at this time.
`isClientCredentialsOAuthClient`	boolean	<optional>	false	if specified, whether or not the auth token should be treated as authorization for an OAuth client with a Client Credentials grant. If you attempt to use a Client Credentials OAuth client and do not specify true for this parameter, the start call will fail with an authentication error.

Returns:

Promise -

returns a promise that will resolve when the session's end processing is complete. If the ArchSession#endTerminatesProcess property is true, this promise will not resolve since the process will be terminated by Architect Scripting during session end processing.

startWithClientIdAndSecret(orgLocation, callbackFunctionStart, clientId, clientSecret, callbackFunctionEndopt, isClientCredentialsOAuthClientopt) → {Promise}

This function starts an Architect Scripting session. You will need to specify the runtime location in which scripting session should run as well as a clientId and clientSecret for your scripting client. The client id and secret are something you create on a per-client basis. The creation of a client id and secret are discussed on the Architect Scripting documentation's main page. If an authorization token is found, it will be used to authenticate this start call. If valid, execution will continue. If an authorization token is not found or it is no longer valid, a login page will be displayed. It is invalid to call this method when the session status is 'running'.

Parameters:

Name	Type	Attributes	Default	Description
`orgLocation`	string			the organization location to use for this session. The string values in `ArchEnums#LOCATIONS` lists valid location values.
`callbackFunctionStart`	callbackSessionStart			the function to call once authorized / logged in where you write code that does work. If a promise is returned from the callback function, the session will wait for the promise to resolve before ending.
`clientId`	string			the client id to use for authentication.
`clientSecret`	string			the client secret to use for authentication.
`callbackFunctionEnd`	callbackSessionEnd	<optional>		if specified, this function will be called when the session is about to end. If the session is configured to end and log out the currently logged in user, this method will be called prior to logging out the user. Any unhandled exceptions encountered during execution of the callback function will not change the exit code set on this session instance. We do not recommend returning a promise from this callback as the session's status will be set to `ended` at this time.
`isClientCredentialsOAuthClient`	boolean	<optional>	false	if specified, whether or not the OAuth client id and secret should be treated as an OAuth client with a Client Credentials grant. If you attempt to use a Client Credentials OAuth client and do not specify true for this parameter, the start call will fail with an authentication error.

Returns:

Promise -

returns a promise that will resolve when the session's end processing is complete. If the ArchSession#endTerminatesProcess property is true, this promise will not resolve since the process will be terminated by Architect Scripting during session end processing.