Creating SOAP RA Web Service Agent Jobs

To run a SOAP web service, you need to create a SOAP RA Web Service Agent Job.

To create a SOAP RA Web Service Agent Job:

  1. Add a Job object of type WEBSERVICE > SOAP and select your Web Service Agent in the Host field on the Attributes tab.
  2. Select the following tab: 
    • In v9: Web Service
    • In v10 and above: SOAP
  3. Select the General menu item on the left side of the screen.
  4. Respond to the fields on the right side of the tab.
    5. Field Description

    Connection

    		 A SOAP Web Service Connection object. The Connection object you select can connect to any Web Service Agent that's available on the client. For more information on SOAP RA Web Service Agent Connection objects, see topic Creating SOAP RA Web Service Agent Connection Objects.

    Service

    		 A non-editable field that shows the service for the selected Connection object.

    Operation

    The available methods for the web service.

    Overwrite URL Endpoint

    		 Allows the Job to override the URL Endpoint from the connection. When checked the URL Endpoint field below becomes editable.

    URL Endpoint

    An optional field where you can override the URL endpoint defined in the Connection object. When this field is non-editable (the Overwrite URL Endpoint checkbox is not selected), the Connection URL Endpoint is shown.

    When the Overwrite URL endpoint checkbox is selected, the field becomes editable and changes to the selected Connection object will have no effect on this Jobs URL Endpoint.

    Output Request and Response to Log

    		 Includes the XML for the request and response in the Job log.

    Create Raw XML SOAP Request Report

    		 Creates a Job report the raw XML for the SOAP request. These reports are written to the soap_reports directory.

    Create Raw XML SOAP Response Report

    		 Creates a Job report with the raw XML for the SOAP response. These reports are written to the soap_reports directory.

    Attachment Type

    Allows you to select from the following attachment options and define attachments. With each, the attachment is contained:

    • Inline - base64 encoded: Within the SOAP envelope and is base64 encoded.
    • SWA - Soap with attachments: Outside of the SOAP envelope and is not base64 encoded. The attachment data comes after the SOAP envelope. The SWA Attachments button is used to define the details of the attachment. For more information, see the Defining Attachments section below.
    • MTOM - Inlined soap with attachments: Within the SOAP envelope and is not base64 encoded. The attachment data is contained in a CDATA tag within the SOAP envelope. This is considered to have better performance than SWA. Base64 encoding makes the attachment size 33 percent larger.

    Output Type

    Allows you to specify a global option to process all attachments returned in the SOAP response no matter the number of attachments returned.  You may choose to use this option rather than defining attachment using the SOAP response editor when you don't know the total number of attachments that will be returned.

    • None: the global response attachment option is not used.
      • Save as Variable: A variable with the name using the prefix you specify in the Output Prefix field is  saved to the database.

      For Automation Engine v9/10, if the size is:

      • Less than 1024 bytes, the value is included in the database.
      • Greater than 1024 bytes, the value is written to <Agent>/bin/variableFileDirectory.

      An Automation Engine scripting language variable's name is limited to 32 alphanumeric characters, including the special characters "$", "_", "@", "§" and "#". German Umlauts are not allowed. The first character must not be a number.

      Script variables set in Web Service Job responses are resolvable in the requests of the following Jobs in the same Workflow. However, they are not propagated to the Workflow.

    • Write to Job Report: Writes the resulting value to the Job's report log  using the prefix you specify in the Output Prefix field.
    • Save as Report: Saves the resulting value to a report in the <Agent>/bin/task_reports directory using the prefix you specify in the Output Prefix field. The file will be registered with the Automation Engine and viewable from the UserInterface. When this option is used, the Web Service Agent expects a parameter value of just a stand-alone file name. If you enter a fully pathed file name, the Job will get an error like the following:

      • java.io.FileNotFoundException: task_reports/u01/users/qa4/v9/RA_WS_Alpha/test3.txt (No such file or directory)

    • Write to File: Writes the resulting value to a file in the Agent's file system. You can enter either a stand-alone file name to write to the <Agent>/bin/task_reports directory on the Agent's file system or a fully pathed file name to a different location on Agent's file system. The file will not be registered with the Automation Engine and is not viewable from the UserInterface.

    Output Prefix

    Used with the setting in the Output Type field, this is an absolute variable or file name. When variables and/or files are returned for attachments, they will use this name followed by _<number>. For example, assume Write to File is selected from the Output Type field, and c:\temp\attachment.txt is entered here. When the SOAP response is returned with three attachments, this option will process all of them by creating three files in the temp directory.  The file names will be attachment_1.txt, attachment_2.txt, and attachment_3.txt.  This allows the Agent to process an unspecified number of attachments when returned.  The file name will contain a number in the name that correlates to the position of the returned attachment.  Using this option supersedes all attachment processing defined in the SOAP response editor. Any attachment definition rules will not be processed.

    Connection Timeout

    		 The number of seconds before timing out while attempting to connect to the URL endpoint. When set to 0, the connection never times out. The default is 30 seconds.

    Read Timeout

    		 The number of seconds before timing out when waiting for a method call. When set to 0, the read never times out. The default is 30 seconds.

    Trace Performance Metrics

    When checked, statistics on how long the call and parsings took are written to the Job log. Additionally, the following object variables are set with the metrics that can be reported upon:

    • COMPILE_REQUEST_DURATION
    • COMPILE_RESPONSE_DURATION
    • ROUNDTRIP_DURATION

    Marshal the SOAP Response

    Determines whether to marshal the SOAP response: 

    • When this box is checked (default): The SOAP XML response is converted to the appropriate Java response object.
    • When this box is unchecked: The SOAP response is not converted and will not be written to the Job report.
  5. Specify request and response settings using the menu items on the left side of the screen as documented in the following topics.

Defining Attachments

To define SOAP with Attachments:

  1. Select SWA - Soap with attachments from the Attachment Handling drop-down list
  2. Click the SWA Attachments button.

    3. The Web Service Agent opens the SWA Attachments dialog where you can define SWA request or response attachments in their own tables.

  3. Click the add icon for the appropriate table.

    4. The Web Service Agent opens a pop-up dialog for the attachment.

    And you enter the following.

    Field Description
    Input Source The file name or URL of the file to attach the file to the SOAP request.
    Content Type

    Allows you to specify the content type.
    Context ID

    Allows you to specify the name of the xml tag this attachment corresponds to.

    At runtime,Axis2 automatically generates replacement variables for each attachment based on the number of attachments specified in the table. The replacement values will be named {attachment_1}, {attachment_2}, etc. The values of these replacement variables are the context ID. You can use these variables in the SOAP request editor to refer to the attachments.

    And you enter the following.

    Field Description

    Output Type

    		 Allows the following options:
    • Save as Variable: A variable with the name you specify in the Output Name field is saved to the database.

      • For Automation Engine v9/10, if the size is:

      • Less than 1024 bytes, the value is included in the database.
      • Greater than 1024 bytes, the value is written to <Agent>/bin/variableFileDirectory.

      An Automation Engine scripting language variable's name is limited to 32 alphanumeric characters, including the special characters "$", "_", "@", "§" and "#". German Umlauts are not allowed. The first character must not be a number.

      Script variables set in Web Service Job responses are resolvable in the requests of the following Jobs in the same Workflow. However, they are not propagated to the Workflow.

    • Write to Job Report: Writes the resulting value to the Job's report log based on the name you specified in the Output Name field.
    • Save as Report: Saves the resulting value to a report in the <Agent>/bin/task_reports directory based on the name you specified in the Output Name field. The file will be registered with the Automation Engine and viewable from the UserInterface. When this option is used, the Web Service Agent expects a parameter value of just a stand-alone file name. If you enter a file name with fully qualified path, the Job will get an error like the following:

      • java.io.FileNotFoundException: task_reports/u01/users/qa4/v9/RA_WS_Alpha/test3.txt (No such file or directory)

    • Write to File: Writes the resulting value to a file in the Agent's file system. You can enter either a stand-alone file name to write to the <Agent>/bin/task_reports directory on the Agent's file system or a file name with fully qualified path to a different location on Agent's file system. The file will not be registered with the Automation Engine and is not viewable from the user interface.

    Output Name

    		 An output name in the Output Name field.

    Context ID

    		 An optional field to specify the context ID in special case scenarios. Usually Axis2 automatically creates the context ID, and you can leave this field empty.

Deleting Registered Files

Registered output files for Web Service Jobs are saved to the task_reports directory under the bin directory. They will remain there until you move or delete them.