Set Up a Web Service

Before calling a web service from a One-Step™ Action, first set up a web service in the Web Service Manager.

When you set up a web service, you define the following:

• General properties for the web service: Name, description, URL, Service Type (REST or WSDL), and Security Type (Basic or None).
• Web Service Method: Define one or more Methods and parameters that are available from the web service.
  Note: WSDL Methods can be generated by parsing the WSDL definition, if available, and generally do not need to be modified.
• Web Service Account: User ID and password required to call the web service (only required when Basic Security is required).
  CAUTION: If you delete a Web Service Account that is used by existing One-Step Actions, the One-Step Actions may no longer work as expected. For best results, edit the existing account information rather than deleting and re-adding it.
  Note: The ability to set up a web service requires security rights.

To set up a web service:

1. Open the Web Service Manager.
2. Optional: Select a scope and subfolder.
3. Select Create New.

   The Web Service Options window opens, showing two pages (General and Methods; Accounts appears later if Basic Security is used).

4. Select the General page.
5. Define general properties for the web service:
   1. Name:

      Provide a display name to use within CSM (search this property in CSM Item Managers).

      It does not have to match the web service, although it is wise to do so.
   2. Description:

      Provide a description to use within CSM (search this property in CSM Item Managers).

   3. URL:

      Provide the URL for the web service (example: http://test.com/webservice/). Select the Selector button (or right-click in the URL field) to insert Tokens into the URL (example: System Functions, Expressions, Stored Values, etc.).

      Note: The URL can also be used as a value in Expressions and Stored Values for use in other areas of the system (example: Use different URLs in Stored Values for development, test, and production environments).
6. Define the Service Type, either:
   • REST: Manually define the Methods and parameters available from the web service (see below).
   • WSDL (SOAP 1.1 or SOAP 1.2): Many WSDL web services expose a WSDL file from which CSM can automatically generate the Methods and parameters that are available from the web service. To parse the items, provide the full path to the WSDL file in the WSDL URL field (example: http://www.test.com/service.asmx?WSDL), and then select the Parse WSDL button when it is enabled. If the web service does not expose a WSDL file, then the Methods and parameters to call must be manually defined (see below).
7. Define the Security Type:
   • None.
   • Basic: If Basic is selected, the Accounts page appears to define the Web Service Account information.
     Note: With Basic authentication, credentials are passed as plain text, so we recommend that you only use it with SSL (https).
8. Define web service call options:
   • Always call web service from Cherwell Server: Select this check box to make all calls to this web service from the Cherwell Application Server (rather than from the client). This is usually done for security reasons, since the web service might be configured to only allow calls from a specific client machine.
   • Log calls to this web service: Select this check box to log web service calls to the Application Server log residing on the server.
     Note: The global system settings might override these options.
9. Select the Methods page.
10. Define a Web Service Method:
    1. Select Add to add a Method.
    2. Define general properties for the Method:
       1. Name: Provide a name for the Method.
       2. Description: Provide a description for the Method.
       3. (Optional) Endpoint: Provide the additional URL path for the Method. Some services have an additional endpoint in the URL to access the Method. For example, if the full path to an addition Method is http://test.com/webservice/addNumbers, the base URL of the service is http://test.com/webservice/ and the endpoint would be addNumbers.
          Tip: Many web services have variable endpoints. Use variables in the endpoint URL by enclosing them in braces { } (example: http://test.com/webservice/{variable}). Provide the variable endpoint parameter directly in the text box, or select the Selector button to add an endpoint parameter using the Web Service Parameter window (see step c below). The parameter is automatically enclosed in braces if you add it using the Web Service Parameter window.
       4. Result Type: Select the data type to use when saving the results:
          • None
          • Text (Default)
          • Number
          • Boolean
       5. Request Type: Select a verb that determines the way a web service is called.
          • POST
          • GET
          • PUT
          • DELETE
          • PATCH
          • HEAD
            Note: For most WSDL web services, the Method should be set to POST. For most REST web services, the Method should be set to GET. Only override these defaults if indicated by the web service’s documentation.
    3. Add the Parameters:
       Note: Most Methods require one or more parameters to be passed to the Web Service Method. For example, addNumbers would likely require passing two numbers that would be added together.
       1. Select Add.
       2. Name: Provide a name for the parameter.
       3. Data Type: Select the data type for the parameter (Date/Time, Logical, Number, or Text).
          Note: With the WDSL (SOAP 1.1 or SOAP 1.2) Service Type, you can pass a text parameter that contains XML representing the full SOAP message. The full SOAP message is included in the web service log if the logging level is set to Debug (refer to Configure Logging for a CSM Server or Web Application for more information).
       4. Parameter Type: Select the type of parameter to pass to the Web Service Method:
          • Standard: Select this option to use the parameter as a regular element in the body content (the parameter value is passed as an argument).
          • Header: Select this option to send the parameter in the header of the call (the parameter value is added to the message header rather than the body content).
          • Endpoint: Select this option to use the parameter in the endpoint URL (the parameter is not passed directly, but is used as a variable in the endpoint URL).
       5. Is SOAP Content: Select this check box if the parameter contains an XML value that includes all of the values (the entire SOAP content) that would otherwise be specified in individual parameters.
          Note: This check box is only shown if WSDL (SOAP 1.1 or SOAP 1.2) is the selected Web Service Method.

       6. Select OK.

11. Select the Accounts page.
    Note: The page is only shown if Basic is selected as the web service Security Type.
12. Define one or more Web Service Accounts:
    Note: The Web Service Account is used when a web service simply requires a User ID and password to be passed with the web service call. You can define multiple accounts (example: A basic account and an administrative account) and select the appropriate account when you define a Call a Web Service Action for a One-Step Action.
    1. Select Add.
    2. Name: Provide a name for the Web Service Account.
    3. Description: Provide a description for the Web Service Account.
    4. User ID: Provide the user name for the Web Service Account.
    5. Password: Provide and confirm the password for the Web Service Account.

    6. Select OK.

13. Select Save.