Creating a custom web service

A custom web service is one in which you modify or add to the basic operation types or XML elements created by AR System server. It might also use an existing XML schema (XSD file), rather than the default XSD created by AR System server. To create a custom web service, follow the steps in this section.

Related topic

Creating-a-basic-web-service

To create a custom web service

  1. In Developer Studio, select File > New > Web Service.
  2. Select the server on which you want to create the web service, and click Finish.
  3. Right-click the General panel, and select Expand All Panels.

    web_services_editor.gif
  4. Click the ellipsis button [...] next to the Form Name field, and select a Base Form from the list of forms.
    The web service operations function through the Base Form.
  5. In the XML Schema field, perform one of these actions:
    • Enter or browse to an external XML schema, and go to step 6.
      With an external XML schema, the elements or complex types in the file are used to map AR Systemform fields to operation parameters. For more information, see Importing-an-external-XML-schema-for-editing.
    • Leave the field blank, and go to step 8.
      Developer Studio creates an XML schema with default element names.
  6. Click Reload.
    AR Systemverifies the XML schema and loads it into memory. You might see a "schema imported successfully" message or a message informing you that your existing XML elements and mappings will be lost.
  7. Select the XML Schema Source type from the list.
    • If you entered a local file system path for your schema, select Embedded.
    • AR Systemstores the entire XSD file and all other files that the XSD file includes or imports. The WSDL also has all the XSDs embedded in the types section. This is the default option.

    • If you entered a network-accessible path (HTTP or FTP) for the schema, select Linked.
      AR Systemdoes not store the XSD files, and the WSDL does not embed the XSDs in the types section. Instead, it refers to them. Some WSDL parsing tools (early versions of Microsoft.NET and MSSOAP) do not support these kinds of WSDL.

      System-generated schemas are always embedded in the WSDL.

  8. (Optional) In the Label field, enter a label for the web service.
    Label names can have 80 or fewer characters, including spaces. The label is displayed in the Web Services list in the server window. If no label is specified, the web service name is used.
  9. (Optional) In the Description field, explain what the web service does and how it can be used so that callers of the web service can determine whether the web service includes the functionality they need.
  10. Right-click the Port tab, select Add Operation, and select an operation type from the list.
    The default operations are displayed in this list. The default operation types are Create, Get, Set, and Service. The default operation names are Create, Get, Set, Service, and GetList. Each operation is defined by its name and type. When you add an operation, the Name field is automatically filled in. You can add multiple operations of the same type.
    For Set operations, there are two additional parameters. You can choose to set all the fields on the form, or you can choose a partial or full composite option. For situations in which this is applicable, see The-Set-operation-type-for-complex-documents.
  11. Customize operations as required.

    To create an operation
    Default mappings are set when you create a new operation.
    a. Right-click the Port tab and select Add Operation.
    b. Select an operation type from the list.
    c. In the Name field, enter a name for the new operation.

    To copy an operation
    Copying an operation retains the existing mapping information.
    a. Right-click the tab corresponding to the operation you want to copy.
    b. Click Add Operation, then select Copy of Selected Operation.
    The new operation appears under a new tab in the WSDL Operations list.
    c. In the Name field, enter a name for the new operation.

    To delete an operation
    a. In the WSDL Operations list, right-click the operation.
    b. Click Remove.

    To change the name of an operation
    a. Locate the operation in the WSDL Operations list, and expand the corresponding tab.
    b. In the Name field, enter the new name.
  12. (Optional) In the Qualification field, enter a qualification.
    When you select a Set or Get operation, the Qualification field is enabled. You cannot use an attachment field as a field reference in a qualification.
    • For the Set operation, you can enter a query that enables the web service to find the request ID of the fields involved if the request ID is not known.
    • For the Get and GetList operations, you can enter a query that identifies the field whose value you want to pass to the web service as the output parameter.
    • If you select a GetList operation, the Start Record and Max Limit fields are populated with the appropriate paths. For more information, see Setting-the-start-record-and-the-maximum-limit.
  13. Map your parameters. For more information, see Mapping-web-service-data.

  14. On the Properties tab, set Permissions, Change History, and Help Text.
    The permissions are the same (Public) whether the web service is visible or hidden.

    If you publish your web service over an internet or intranet for general use, set the permissions to Public.

  15. Click File > Save to save your web service.
    The name of the web service should be descriptive and indicative of the web service's function. The name should not be the same as any existing active link guide, filter guide, packing list, or application.
  16. Click the WSDL Publishing Location tab.
    A sample URL for your WSDL file is displayed in the Specify mid tier's WSDL handler URL field.
  17. Adjust the URL for your configuration:
    1. Replace <midtier_server> with the name of the web server where the Mid Tieris running.
    2. Add /public or /protected after "WSDL," depending on the permissions of the web service.
    3. Replace "Untitled Web Service" with the name of the web service.
      For example, if the web service has public permissions, use this format:
      http://midtierServer/arsys/WSDL/public/ARServer/webServiceName
    4. If the web service does not have public permissions, use this format:
      http://midtierServer/arsys/WSDL/protected/ARServer/webServiceName
  18. Click View.
    Your WSDL file is displayed on the tab.
  19. After all the adjustments are made, save the web service.
    When you save the web service in AR System server, the program creates a WSDL file that describes the web service. This file contains all the details necessary to interact with the service, including message formats, transport protocols, and endpoint location.
    The WSDL file can be accessed with a URL using one of the following syntaxes.
    • If the web service has public permissions, use this syntax:
      http://<midtierServer>/arsys/WSDL/public/<ARServer>/<webServiceName>
    • If the web service does not have public permissions, for example, if it is used only inside a private network, use this syntax:
      http://<midtierServer>/arsys/WSDL/protected/<ARServer>/<webServiceName>
      After you save your web service, it is ready to use. To verify that your web service is ready, enter the WSDL URL into a browser address field.

      web_services_wsdl.gif

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*