Defining a Web Services Connection

Create a connection to the Web Services host before TA can run your Web Services jobs. These connections also must be licensed before TA can use them.

A Web Services connection represents a connection to a single REST or SOAP Web server and one service defined in its WSDL. A single installation allows for multiple connections to be established to various REST and SOAP Web Services providers.

A connection is created through the Connection Definition dialog.

Adding a SOAP Web Services Connection

To add a SOAP Web Services connection:

  1. Click Administration > Connections on the Navigation pane to display the Connections pane.

  2. Click Add or right-click and choose Add Connection > WebService Adapter from the context menu to display the WebService Connection Definition dialog.

  3. Enter a name for the new connection in the Name field.

  4. Click the General tab.

  5. Click the maximum number of concurrent active processes that TA should submit to the Web Services host on this server at one time in the Job Limit field.

  6. Click the name of a default user for Web Services jobs in the Default Runtime User list.

    The runtime user is used for HTTP authentication. Only users that have been defined with Web Services passwords display in this list. The user selected is automatically supplied as the runtime user in TA Web Services job definitions.

    Note: If you intend to connect Web Services adapter to another TA 6.x platform, click a user account from the "Interactive User" group. Only an interactive user is allowed to connect to a TA platform.

  7. Click the Web Service tab. The Web Service Type dialog appears.

  8. Click the SOAP Web Service option, and then click OK to display fields related to SOAP Web Service.

  9. Click either From File or From URL to load the WSDL file.

    Note: When attempting to process a WSDL file containing DTD and external links, this error message may appear on the user interface: Failed to read the external document 'burp', because 'http' access is not allowed due to restriction set by the accessExternalDTD property. To resolve this, disable the parameter by adding XmlFeatureSecureProcessing=N to the clientmgr.props file.

    • From File – Load the WSDL file from an existing file via the WSDL From File dialog.

      Due to internet browser security constraint, WSDL upload from file will be successful only if the WSDL is self-contained and does not import a schema or other WSDL's. To supply WSDL that imports other files, you must download it through the From URL option.

    • From URL – Load the WSDL file from a WSDL URL

      Note: You can also import a schema from within a WSDL. To import a schema, load the WSDL. If the WSDL imports any schemas, the adapter will follow the reference paths to load them. If the schema imports additional schemas, the adapter will load every one.

      If HTTP Authentication is required to access the WSDL URL on the Web server, specify the HTTP Authentication user for the connection first, then load the WSDL from the URL.

  10. Click a service from the Selected Service list.

    The Web Services connection is defined by selecting a service defined in a WSDL file.

  11. Click OK after selecting a file or entering a WSDL URL.

    Optionally, in the HTTP Authentication section and the SOAP Authentication section, choose an authorized runtime user from the list for use with Web service jobs.

  12. Click OK.

    Note: See Tidal Automation User Guide for instructions on using the Options, Outages, and Description tabs. These tabs are not specific to this adapter.

Adding a REST Web Services Connection

A REST Web Services is a stateless client-server architecture in which clients access and manipulate Web resources through HTTP protocol. It does not introduce additional specification (as oppose to SOAP/WSDL) on top of the existing HTTP methods, definitions, and entities. This means an HTTP client can interact with a REST Web Service provider without having to incorporate any supporting stack. You can create a REST connection without authentication, with HTTP authentication, or with OAuth authentication.

Without Authentication

To add a REST connection without authentication:

  1. Click Administration > Connections on the Navigation pane to display the Connections pane.

  2. Click Add or right-click and choose Add Connection > Web Services Adapter from the context menu to display the Web Services Connection Definition dialog.

  3. Enter a name for the new connection in the Name field.

  4. Click the General tab.

  5. Click the maximum number of concurrent active processes that TA should submit to the REST Web Service host on this server at one time in the Job Limit field.

  6. Click the Web Service tab. The Web Service Type dialog appears.

  7. Click REST Web Service, and then click OK. The Web Service tab appears.

  8. Enter the URL for the REST service in the Base URL field.

  9. Click None from the Authentication section.

  10. Click OK.

With HTTP Authentication

To add a REST connection with HTTP authentication:

  1. Click Administration > Connections on the Navigation pane to display the Connections pane.

  2. Click Add or right-click and choose Add Connection > Web Services Adapter from the context menu to display the Web Services Connection Definition dialog.

  3. Enter a name for the new connection in the Name field.

  4. Click the General tab.

  5. Click the maximum number of concurrent active processes that TA should submit to the REST Web Service host on this server at one time in the Job Limit field.

  6. Click the Web Service tab. The Web Service Type dialog appears.

  7. Click REST Web Service, and then click OK. The Web Service tab appears.

  8. Enter the URL for the REST service in the Base URL field.

  9. Click HTTP Authentication on the Authentication section.

  10. Click the runtime user for Web Service that represents those users and passwords required for HTTP Authentication from the User list.

  11. Click OK to save the connection.

With OAuth 1.0 Authentication

To add a REST connection with OAuth 1.0 authentication:

  1. Click Administration > Connections on the Navigation pane to display the Connections pane.

  2. Click Add or right-click and choose Add Connection > WebService Adapter from the context menu to display the WebService Connection Definition dialog.

  3. Enter a name for the new connection in the Name field.

  4. Click the General tab.

  5. Click the maximum number of concurrent active processes that TA should submit to the REST Web Services host on this server at one time in the Job Limit field.

  6. Click the Web Service tab. The Web Service Type dialog appears.

  7. Click REST Web Service, and then click OK.

  8. Enter the URL for the REST service in the Base URL field.

  9. Click OAuth 1.0 on the Authentication section.

  10. Enter these values that are required to authenticate with the service provider. You should have obtained the Consumer Key and Secret after registering your Web Service application with the provider.

  11. Click one of these options in the Send OAuth Parameters by section:

    • Authorization Header

    • Form Parameter

    • Query Parameter

    Optionally, click Additional OAuth Parameters to add or edit additional OAuth parameters. The Additional OAuth Parameters dialog appears.

    1. Click Add or Edit to display the OAuth Parameters dialog.

    2. Enter the parameter name in the Name field.

    3. Enter the parameter value in the Value field.

    4. Click OK to return to the Additional OAuth Parameters dialog.

    5. Click OK to return to the Web Service tab.

  12. Click OK to save the connection.

Running the OAuth 1.0 Authentication Wizard

To use OAuth 1.0 authentication, you are required to authenticate with the service provider with four values, Consumer Key, Consume Secret, Access Token, and Token Secret.

Note: The OAuth 1.0 Authentication Wizard will only work with Web Service providers that support the Out of Band (OOB) callback mechanism.

To acquire or renew these values:

  1. Click Authorize on the Web Service tab to launch the wizard.

  2. Enter these values that are required to authenticate with the service provider on the Authorization panel. You should have obtained the Consumer Key and Secret after registering your Web Service application with the provider.

    • Consumer Key

    • Consumer Secret

    • Permission Scope

    • Request Token URL

  3. Click Next to connect to the Web Service provider and view the response.

  4. Click View Response to display the View Response panel.

  5. Click OK to return to the Authorization panel.

  6. Navigate to the Authorization URL field and enter the authorization URL and Request Token value displayed in the Request Token field above in the format required by the Web Services provider.

    Example: A typical format is as follows: https://www.provider.com/oauth/authorize?oauth_token=<request token>

  7. Click Authorize to display the Web Services provider Website and follow the instructions provided to authorize your application and obtain the Verifier code.

  8. Return to this wizard when complete, then click Next to continue with your OAuth authorization. The Verifier and Access Token URL panel appears.

  9. Navigate to the Verifier field and enter the verifier you obtained in Step 7 above.

  10. Enter the URL you obtained from the Web Service provider in the Access Token URL field.

  11. Click Next. The Access and Token Granted panel appears.

  12. (Optional) Click View Response to display the View Response panel.

  13. Click Finish to save the values and return to the Web Service tab.

With OAuth 2.0 Authentication

To add a REST connection with OAuth 2.0 authentication:

Note: If you are setting up for Password Grant, create a TIDAL runtime user with the OAuth2 username and password that are required to log into your authorization server. Then continue the configuration steps as follows:

  1. Click Administration > Connections on the Navigation pane to display the Connections pane.

  2. Click Add or right-click and choose Add Connection > Web Services Adapter from the context menu to display the Web Services Connection Definition dialog.

  3. Enter a name for the new connection in the Name field.

  4. Click the General tab.

  5. Navigate to the Job Limit field and click the maximum number of concurrent active processes that TA should submit to the REST Web Service host on this server at one time.

  6. Click the Web Service tab. The Web Service Type dialog appears.

  7. Click REST Web Service, and then click OK.

  8. Enter the URL for the REST service in the Base URL field.

  9. Click OAuth 2.0 in the Authentication section. If you are creating a connection using the new version of the adapter, continue to step 11.

  10. Check Switch to new view checkbox to convert the connection configured in the old format to the new format.

    Note: Switch to new view checkbox is displayed only when you are editing an existing connection created using an earlier adapter version. When you check this checkbox, it converts the connection configured in the old format to the new format. If you are creating a connection using the current version, then this checkbox is not displayed.

  11. Click the desired grant type. Enter all the required information.

    If you click Password option in the Grant Type field, then choose the runtime user you created earlier from the User dropdown list.

    Note: You can leave the Scope field blank, if your authorization server does not require it.

  12. Save the connection.

Enabling Web Service Proxy

You can set the proxy settings for the Web Services adapter.

To set the proxy settings:

  1. Click the Proxy tab on the Connection Definition dialog.

  2. Check the Use Proxy checkbox.

  3. Enter the proxy server address in the Host field.

  4. Enter the port number in the Port field.

  5. Enter the scheme (https or http) in the Scheme field.

  6. (Optional) Check the HTTP Authentication checkbox.

  7. Enter the user ID and password in the respective fields.

  8. Click OK.

Web Services Connection – Options Tab

The Options tab allows you to specify polling for the connection and add any configuration parameters.

This tab contains these elements:

  • Connection Poll – The frequency (in seconds) in which the Web Services instance is checked for new connect messages. The default value is 5 seconds. Values can range from 1 - 999 seconds.

  • Time Out – The amount of time to wait for the connection to establish before timing out. The default value is 75 seconds.

  • Configuration Parameters – Specify any parameters that are used during polling.

    OLDRECOVERYLOGIC – By default, when the connection is lost and then restored, the adapter sets the status of Orphaned jobs to Unrecoverable. In earlier adapter releases, the adapter sets the status of Orphaned jobs to Completed Abnormally. To restore the old behavior, specify OLDRECOVERYLOGIC=Y.