interview Object

The interview object allows access to various aspects of the interview using the properties and methods given in the following table.

Table 1. The interview object methods
Property or Method Description
deploymentName A field that allows the interview name to be accessed
locale A field that returns the current locale string
resourcePath A field that returns the base URL for any custom resources bundled with the policy model
restart() Restarts the interview
submit() Submits data on the current screen and transitions to the next screen in the interview
back() Navigates to the previous screen in the interview
getNavigation() Returns an object that contains the current stage and screen list
getStages() Returns an array of the currently visible stages. See Table 2.
getScreens() Returns the visible list of screens inside the current stage. See Table 2.
currentScreen() Returns an object that has properties for the current screen. See Table 3.
navigate(investigateUri) Navigates to the interview screen specified by the investigateUri. The investigateUri cannot be null.
update() Causes all the controls to be updated. Useful for triggering a re-render after an asynchronous event has occurred.
setInputValue(name, value, entity?, instance?) Allows a value to be directly set for an editable (that is, not read only and not hidden) input control on the screen. If the value exists in the global entity instance you don't need to specify the entity or instance name. However, if the value is not in the global entity instance you must specify both the entity and the instance name. The entity and instance are available as properties of both the control and screen objects.
getValue(name, entity?, instance?) Allows a value to be read for a value on the screen. If the value exists in the global entity instance you don't need to specify the entity or instance name. However, if the value is not in the global entity instance you must specify both the entity and the instance name. The entity and instance are available as properties of both the control and screen objects.
hasError() Returns true if the control is currently displaying an error message. See Example 12 in Examples of Control Restyling.
needsAnswer() Returns true if the control still needs an answer to be provided. A control still needs an answer if: (i) it is an input control or upload that is mandatory and no answer has been provided, (ii) an invalid answer for the control data type has been provided, or (iii) it is a text input control and "" has been provided. See Example 12 in Examples of Control Restyling.
getExtensionData() Returns the current values of all the items specified in the opm.extension.data.json file. Allows a value to be read for an attribute not on a screen.
saveData(options?) Saves the valid data on the current screen in the session. The properties for the options object are set out in Table 4.
getAvailableLanguages()

Returns the set of languages available for this session in the form of an array of objects with the following properties:

  • locale : the locale code (for example, en-GB)
  • displayName: the display name specified in the policy model for the language (for example, English)
changeLanguage(locale) Changes the interview language for the current session
fetch(options?) Invokes an interview extension connection to load and save data. The properties for the options object are set out in Table 5. This method returns a Promise containing a Response object containing the response returned by the interview extension connection. The Response object is defined by the Fetch API (see https://developer.mozilla.org/en-US/docs/Web/API/Response for more information).
sendCustomEvent(event) Sends the custom event to the embedding application onCustomEvent handler and returns the value that is returned by that handler. There is no constraint on what is passed in the event, that is, the value is directly passed through. Note that if the interview is not running embedded, or the embedding page does not supply an onCustomEvent handler, then sendCustomEvent will do nothing.
destroy() Terminates the interview and frees up associated browser resources. The optional properties for the destroy method are set out in Table 6.
ping() Defers the interview session expiry. (Equivalent to clicking the Keep Working button on the timeout expiry warning dialog.) Returns a Promise<boolean> which will resolve to true if the session expiry was successfully deferred, or false if the session has already expired.

Properties returned from the getStages() and getScreens() methods are given in the following table.

Table 2. Properties for the getStages and getScreens methods
Property Description
caption The caption of the stage/screen
title The title for the stage/screen. This combines the caption with the current completion status. This can be useful for accessibility.
state The active/completion state of the stage/screen. Can be complete, incomplete, activeComplete, activeIncomplete, or future.
investigateUri The investigateUri suitable to be passed to the navigate method of the interview object. This will be null if the interview does not allow navigation to the particular stage/screen, which means the navigate method on the interview object cannot be used.
isCurrent Returns true if the stage/screen is the current stage/screen, otherwise returns false
isComplete Returns true if the stage/screen is complete, otherwise returns false
isFuture Returns true if the stage/screen has not yet been visited, otherwise returns false

Properties returned from the currentScreen() method are given in the following table.

Table 3. Properties for the currentScreen method
Property Description
hasBackButton() Returns true if the screen requires a back button
hasNextButton() Returns true if the screen requires a next button
hasRestartButton() Returns true if the screen requires a restart button
hasExitButton() Returns true if the screen requires an exit button
getBackCaption() Returns the caption for the back button
getNextCaption() Returns the caption for the next button
getRestartCaption() Returns the caption for the restart button
getExitCaption() Returns the caption for the exit button
getProperty(name) Returns the value of the specified custom property on the screen
getControls() Returns an array of the top level controls that are on the screen

Properties for the options object provided to the saveData() method are given in the following table.

Table 4. Properties for the saveData method
Property Description
resumeOnCurrentScreen

If true, any created checkpoint will resume on the current screen. If false or unspecified, any created checkpoint will be resumed on the next screen.

Note: A checkpoint will only be created by calling the saveData method if:
refreshSeedData

If true and the deployment's connection supports seed data refresh, then a seed data refresh will be triggered. Defaults to false.

Note: For a connector to support seed data refresh:

  • the connector must be a web service connector, and

  • the Submitted data becomes read-only setting in the Mapping Settings dialog in Policy Modeling must be deselected. For more information, see Allow Interview Data to Be Re-Submitted.
createCheckpoint

If true and the deployment's connection supports checkpoints, then a checkpoint will be triggered. Defaults to false.

Note: Whether or not a connection support checkpoints is defined by its metadata. For this option to work:

  • the policy model must be recompiled in the 20D Monthly update 1 version of Policy Modeling or later, and

  • the Checkpoints setting for the interview in Policy Modeling must be set to something other than Disabled. For more information, see Select the Screens That Will Create Checkpoints. If checkpoints are enabled for the screen, a checkpoint will still be created by calling this method irrespective of this property's value.
callback Must be a function that takes a single argument "response" which is an object with a single boolean property "success". Note that "success" refers to the success of the HTTP request sent to the Intelligent Advisor server. It will be true if the saveData HTTP request has been successfully received and processed by the Intelligent Advisor server. This means that the HTTP request did not timeout or return with an error code. If there are page validation or submit errors, "success" will still be true.

Note: The order of processing for the saveData() method is: (1) Save valid data on the current screen into the session. (2) If a checkpoint should be created, create a checkpoint. (3) If a seed data refresh should be triggered, trigger a seed data refresh. (4) Return and render the updated screen.

Properties for the options object provided to the fetch() method are given in the following table.

Table 5. Properties for the fetch method
Property Description
connectionName Required. The name of the Hub interview extension connection to use
method Required. The request method (GET, POST, PUT, DELETE, PATCH or TRANSCRIPT). Where the method is TRANSCRIPT, this generates and sends a session transcript via the nominated interview extension connection using a POST operation. For more information, see Get a Transcript of an Interview Session.
relativeUri Optional. A URI that is interpreted as the relative URL of the configure connection. The relative URI may contain query parameters. The URI must resolve to a sub-resource of the connection URI so you cannot have back references (that is, ../../) elsewhere. It is the caller's responsibility to ensure the URI is encoded correctly.
body Optional but ignored for GET and TRANSCRIPT requests. A UTF-8 encoded string representing the payload to be sent for this request. Any body data can be sent (including interview attribute values).
contentType Required if a body is supplied. The mime type of the body content. REST/SOAP or any other content protocol can be used. Ignored if method is TRANSCRIPT (for TRANSCRIPT operations, the content type is always application/json).
headers Optional. The set of additional headers to send in the connection request. It is the caller's responsibility to ensure that any HTTP headers provided in the fetch request are correctly formed. If the interview extension connection is configured to pass through an authorization header from interview extensions, you can pass an Authorization header. Intelligent Advisor is not responsible for the security, acquisition, verification or validation of any authorization credentials provided by the caller. Note: The content type header cannot be set via this method.
transcriptVersion Only applicable where method is TRANSCRIPT. Optional. Specifies the version format for the session transcript file (either 12.2.40, 12.2.30 or 12.2.21). If not specified, defaults to 12.2.21.
additionalSessionData Only applicable where method is TRANSCRIPT. Optional. An array of attribute and relationship names whose values you want to see in the contextSessionValues section of the transcript. Nominated attributes and relationship values will be provided for every instance in which they exist.

Note: Cookies can prevent Safari and other browsers from using extensions that require interview.fetch() when the Intelligent Advisor site hostname differs from the parent site.

Properties for the destroy() method are given in the following table.

Table 6. Properties for the destroy method
Property Description
terminateInterview Optional. If true, un-renders the interview and destroys both the interview session on the server and the client. Otherwise, interview.destroy() only un-renders the interview. Defaults to false.