› Integration › Web service references › Manage a web service reference

Manage a web service reference

You can manage a web service reference and view associations for a web service reference (that has Open API definition and non-Open API REST services) on the Web service references page.

To open a Web service references page, navigate to Integration > Web service references. All the web service references that have Open API definitions and non-Open API REST services are listed.

Once a web service reference is created, you can create a web service activity or add a web service event to interact with internet web services. You can call any web service with a public class and public methods from a web service activity. Each public method has a list of parameters to which you must assign variables.

Use the following links to learn how to manage a web service reference:

Create a web service reference

  1. On the Web service references page, click New.

    The New web service reference dialog box is displayed.

  2. Select a web Service type to configure. Available options are:

    Service type

    Description

    SOAP (Default)

    Specify the URL that references the Web Service Description Language (WSDL) file for the web service. For example, http://localhost/PlatformManagerWs/PlatformManagerWs.asmx?WSDL.

    If the "Allow all" system setting is not enabled, you can only provide a whitelisted web service URL and Endpoint URL; otherwise, a message appears stating the connection is denied because the URL connection string is not whitelisted.

    SOAP WCF

    Specify a web service URL with a .svc extension.

    If the "Allow all" system setting is not enabled, you can only provide a whitelisted web service URL and Endpoint URL; otherwise, a message appears stating the connection is denied because the URL connection string is not whitelisted.

    RESTful

    Specify the URL which maps the HTTP methods: GET, PUT, POST, and DELETE. See RESTful Service activity and Configure a RESTful Service activity.

    If the "Allow all" system setting is not enabled, you can only provide a whitelisted web service URL; otherwise, a message appears stating the connection is denied because the URL connection string is not whitelisted.

    RESTful Open API

    Do the following:

    1. Specify a valid Open API URL that describes the API.

      If the "Allow all" system setting is not enabled, you can only provide a whitelisted Open API URL and Endpoint URL; otherwise, a message appears stating the connection is denied because the URL connection string is not whitelisted.

    2. Select the definition type as JSON or YAML. (Default: JSON)

    3. Select the Method names to use: Use Operation ID or Use HTTP verb. (Default: Use Operation ID)

    See Web services supported by TotalAgility for more information about supported web services.

  3. Enter a Name for the web service.
  4. By default, the system automatically saves a new web service reference in your working category. To store the web service reference in a different category, select a category on the Category list.

    The categorization of web services helps restrict access to web services to specific users.

    When you export/import a process map or a form that has a web service, TotalAgility also exports/imports the category of the web service. If the category does not already exist, TotalAgility also creates the category for the web service.

  5. Use the Endpoint URL for changing the web service execution location without regenerating the web service proxy DLLs. For example, use the Endpoint URL to dynamically change the execution location from the Test server to the Production server to facilitate migration. To specify the URL, perform the following steps:
    1. Click Yes for Endpoint URL. (Default: No)
    2. Enter the endpoint URL.

    The Endpoint URL must be the location of the web service and not the WSDL link. The Endpoint URL is only supported for SOAP and WCF; it is not supported for the RESTful web services.

  6. To control access to the web service and not just restrict access to the configured TotalAgility Enterprise services account, select any one of the following options for Authentication:

    Basic

    Enter the User name and Password for endpoint.

    OAuth 2.0

    Select the OAuth server from the OAuth server list.

    • This option is only available for RESTful service type. When you export and import a process map or a form that has a RESTful service type, you can also export and import the associated OAuth servers.

    • When a RESTful web service with an integrated OAuth server is executed (using a process map or form), any expired access tokens are refreshed automatically for a successful web service execution. This does not apply to the OAuth servers for which access tokens are not generated.

    Certificate

    Click browse and upload a certificate to use to authenticate with the web service and enter the password in Certificate password.

    If the certificate is not valid, an error is displayed at runtime.

    Basic (external)

    Enter the secret name for the username and password stored in the configured external storage.

    None (Default)

    No authentication is required.

  7. To add a custom header to a web service, perform the following steps:
    1. Click for Custom header.
    2. Enter a Name, such as Host.
    3. Enter a Value, such as localhost.
    4. Click Add.
  8. Click Save.
    If the service is valid, TotalAgility Designer generates a proxy stub DLL.

Modify a web service reference

When you modify the web service reference that has an Open API definition and save the changes, the proxy stub DLL is regenerated.

  1. On the Web service references page, click the web service reference to open it for modification.
    The Edit web service reference dialog box is displayed.
  2. Make changes as needed.
  3. Click Save.

Delete a web service reference

On the Web service references page, on the context menu of the web service to delete, click Delete.

On confirmation, the selected web service is deleted.

You cannot delete a web service reference that is already in use. You can view the associations for that web service to see the items in which the web service is being used.

View associations for a web service reference

You can view the items associated with a web service reference that has an Open API definition and non-Open API services, such as processes and forms being used by the web service reference.

On the Web service references page, on the context menu of the web service reference for which to view the associations, click Associations. The Integration associations - <web service reference name> dialog box displayed.

The names of items are displayed as hyperlinks. You can click the item name link to open the item in a new browser tab and make changes, as needed.

How to: Use a Web service reference