Connect to a Specific External Application

Connector Framework Web Service Connections defined in Intelligent Advisor Hub are used to communicate between Intelligent Advisor and specific external applications via a web service connector. After a Connections administrator has configured a connection in Intelligent Advisor Hub, it can be used by multiple policy models which connect to that Hub.

Using a connector framework web service connection:

policy modelers set up data mappings to the connected application
data can be loaded and saved from the connected application during Intelligent Advisor interviews
Determinations API web services can be used in terms of the project data mappings

To create a new connector framework web service connection:

Ensure the application you wish to connect to has a connector framework web service connector.
In Intelligent Advisor Hub, navigate to the Connections Page.
Click Create. The New connection page opens.
In the CONNECTION SETTINGS section:
- In the Name field, enter a name for the connection. This name will appear in Policy Modeling and on interview screens, so ensure it is suitable for display in a public-facing user interface.
- In the connection Type drop-down list, select Connector framework.
- In the Workspace access options, select the check boxes for the workspaces that you want to have access to the connection.
In the CONNECTOR FRAMEWORK DETAILS section:
- In the Interface options, select Web service.
- In the URL field, enter the URL of the web service connector for your application. For example, https://<your_server>/<your_web_service_connector_name>/soap. Note that:
  - The standard ports are 443 (for https) and 80 (for http) and these do not need to be specified in the connection URL. Web service connections using non standard ports may experience difficulties when sites are transported between data centers and for this reason it is recommended that standard ports are used.
  - https is recommended, as transferring information over http is not secure.
  - For connections using https, the server hosting the web service connector must support Transport Layer Security (TLS) 1.1 or later. TLS 1.0 is not supported. TLS 1.2 is recommended.
- In the Version drop-down list, select the web service version.
- (Optional) In the SOAP action pattern field, specify the soap:operation soapAction name expected by the web service. (Note that this option is only available for 12.2 or later versions of the web service.) This allows, for example, a single URL to handle multiple connectors. Note that:
  - The placeholder {0} must be used to represent where the web service connector action name should appear in the soapAction name. For example, MyPrefix:{0} would expand to MyPrefix:Save for the Save operation, and to MyPrefix:Load for the Load operation.
  - If no SOAP Action Pattern is specified, all the SOAP Actions are their default: CheckAlive, Load and Save.
  - Once saved, the final SOAP operation action names can be verified using the download Web Service WSDL action in the connection dialog box.
- (Optional) Select the option Requires custom root certificate to use a custom root certificate defined in Intelligent Advisor Hub. These custom root certificates will be recognized by outbound https calls made by an Intelligent Advisor site. If not selected, the connection will only trust the built-in root certificates.
- (Optional) In the Present this client certificate drop-down list, select a client certificate. This client certificate will be presented to the server if requested by the HTTPS connection. Note that if the connection is configured with a client certificate that doesn't exist, the connection will ignore it.
In the OAUTH FOR DATA OPERATIONS section:
- (Optional) Select the option Provide OAUTH bearer token in HTTP header on Load, Save, GetCheckpoint, SetCheckpoint and ExecuteQuery actions. If this option is selected:
  - In the URL parameter field, enter a URL parameter. The token's value is passed by specifying the parameter in the query string of the interview's startsession URL. This value will then be passed to the web service connector as an OAuth 2.0 HTTP Authorization header whenever a Load, Save, GetCheckpoint, SetCheckpoint or ExecuteQuery request is sent. For more information, see The OAuth 2.0 Authorization Framework and The OAuth 2.0 Authorization Framework: Bearer Token Usage.
In the COOKIE PARAMETER section:
- (Optional) Select the option Provide the named cookie as a parameter in the request context Load, Save, GetCheckpoint and SetCheckpoint actions. If this option is selected:
  - In the Cookie name field, enter the name of the cookie to get passed through when the interview is started or resumed. The cookie's current value will be passed allowing OAUTH tokens to be renewed. Note that this feature is only available for Latest Version interviews.
In the WS-SECURITY section:
- (Optional) Select the option Provide WS-Security username token in SOAP actions. If this option is selected:
  - In the Username field, enter a username for the purpose of connecting securely to the web service. Note that this is not related to the username of the logged-in Intelligent Advisor Hub user.
  - In the Password field, enter a password.
  - In the Applies To options, select All or Metadata only.
  - (Optional) Select the option to Include timestamp with a 5 minute expiration. Note: The web service connector time must be synchronized to Intelligent Advisor server.
Click Apply.
On the Connections page, check that the status of the new connection is Online.

The username and password supplied in the connection WS-Security settings are sent to the web service at the given URL within the Security element defined in the Oasis security XSD. For example:

<s:Header>
    <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
        <o:UsernameToken>
            <o:Username>serviceuser</o:Username>
            <o:Password>servicepassword</o:Password>
        </o:UsernameToken>
    </o:Security>
</s:Header>

These credentials are used for all requests sent from Intelligent Advisor Hub. These requests may be:

metadata requests from Policy Modeling (at design time) to enable entities and attributes in the policy model to be mapped to tables and fields in the application
data requests from an Interview service (at runtime) to enable:
- loading and saving of data to the application,
- resuming and storing checkpoints to the application, or
- executing dynamic data queries
a simple ping to check if the web service connection is online.