Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Simple Object Access Protocol (SOAP) is a standard protocol specification for message exchange based on XML. Communication between the web service and client happens using XML messages. You can create Consumer/Provider activities with the SOAP Web Service using Adeptia Suit.

...

You can use Web Service Consumer activity to access any Web Service (internet/ intranet). You can use this activity to send request to and receive response from the Web Service. To create this activity, you need to have the WSDL or the endpoint of the Web Service, which you want to access.
In the Adeptia Suite, you will get EasyWSDL Parser, which is a new WSDL parser for Web Service Consumer activity. This EasyWSDL parser has the following additional benefits:

  • It is more robust than WSDL4j
  • It is more reliable than WSDL4j

...

  • When you use WSDL4j as your WSDL parser, then the process to create any new WS Consumer activity will remain the same as earlier.
  • When you use EasyWSDL as your WSDL parser then:
    • Any new WS Consumer activity that you create will use EasyWSDL parser.
    • You don't have to select the Operation while creating the WS Consumer activity.
    • You don't have to create an XML Schema for this Consumer activity. You can directly load the WS Consumer activity, in the Data Mapper and select the operation in the Data Mapper.
      To know how to load a WS Consumer activity in the Data Mapper, refer to the Loading Web Service Consumer in Data Mapper section.
    • You cannot use the Web Service to create an XML Schema.
    • If you edit any existing WS Consumer activity in the Adeptia Suite V6.1 or above, that you made using an earlier version of the Adeptia Suite then, the Adeptia Suit will use WSDL4j parser to edit it.

 

Info
  • If you create any WS Consumer activity using the WSDL4j parser then, the Adeptia Suite will always use that parser to edit the activity irrespective of the WSDL parser that is currently configured on the Adeptia Suite.
  • Similarly, if you create any WS Consumer activity using EasyWSDL parser then, the Adeptia Suite will always use that parser to edit the activity irrespective of the WSDL parser that is currently configured on the Adeptia Suite.

This feature is available in:

Enterprise

Premier

Profession

Express

 

...

Creating Web Service Consumer Activity using EasyWSDL Parser

...

Steps to create Web Service Consumer activity using EasyWSDL Parser

  1. On the Adeptia Suite homepage, click the Develop tab.
  2. Go to Services > Web Services and then click Consumer. This action will display you the ConsumerManage screen (see Figure 305).

    Image Removed

    Figure 305: Consumer Manage Screen

  3. Click the CreateNew link. This action will display you the New Web Service Consumer screen (see Figure 306).

    Image Removed

    Figure 306: New Web Service Consumer Screen

  4. Enter the name and description of the new activity in the Name and Description textboxes respectively.
  5. In case the WSDL file contains characters that do not fall into the default character set encoding then, you can change it in the Character Set Encoding textbox. By default, this textbox displays the character set encoding that you have defined at the application level.

    Info

    You can check the Service Name and Bindings of a WSDL file to verify its character set encoding.

  6. Ensure that the Consumer Type is SOAP.
  7. Select the URI Location of the WSDL file. Select HTTP radio button if your WSDL file is on a HTTP location. If your WSDL file is on a local machine or on a LAN network then, select the Local/LAN radio button.
  8. If you select the HTTP radio button in the previous step then, enter the HTTP URL in the WSDL URL (HTTP URL) field.
  9. If your wsdl file is on local machine or on a LAN network then select Local/LAN radio button in the previous step.
  10. In case your WSDL file is referring to another file, you can either choose an existing file reference activity from the File References drop-down list or click on the Image Removed button to create a new file reference activity. You can also click on the Image Removedbutton, if you want to update an existing file reference activity.

    Info

    To know how to create a file reference activity, please refer to the Creating a File Reference Activity section.

  11. If your WSDL file is on a local network then enter its path in the WSDL File Path (Local/Lan) field. Click the Browse WSDL button to select the WSDL file path. This action will open the Upload WSDL File window (see Figure 307).

    Image Removed

    Figure 307: Upload WSDL File Window

  12. Click the Browse button to choose the WSDL file and then click the Upload File button to upload the file (see Figure 308).

    Image Removed

    Figure 308: Create Web Service Consumer Activity

  13. Click the Next button. This action will show you the Web Service Consumer screen (see Figure 309 ).

     

    Image Removed

     

     

    Figure 309: Select binding for Consumer Activity Screen

    Info

    If there is only one service name in your WSDL file then the Adeptia Suite will show that service name as selected. If there are multiple service names in your WSDL file then the Adeptia Suite will show you all the services in a drop-down list options in the Service Name field. In this case, you have to select the service that you want.
    When you select the service name, it will then populate the Binding field automatically. This field displays only those bindings, that correspond to the service name, which you will select in the Service Name field. If in the WSDL definition file there is only one binding for any service name then, by default you will see only that binding in the Binding field. However, if there are multiple bindings for a service name then, you will see all the bindings in the drop-down list.

    Info

    A lot of WSDL files by default come with a dummy endpoint that do not point to the actual location of the service, but instead contains a dummy link, for example - http://example/servicename

    This is because sometimes the WSDL file describes what the service looks like, but do not point where it is located. Therefore it should be possible to override the endpoint from within the Web Service Consumer configuration instead of having to do via the Process Designer.

  14. Click the Next button. This action will show you the Consumer Standard Properties, WSA Addressing Properties, and Advanced Properties (see Figure 310).

    Image Removed

    Figure 310: Web Service Consumer Properties Screen

  15. If the Web Service that you want to access is secured then, select a security policy activity from the Security Policy dropdown list.

    Info

    You may also override the security policy activity that is being called within a consumer activity. For this, there is a context variable, securityPolicy. It is accessible via put-context-var action of a process flow designer. For details, refer to the following sections:

    To learn about its Advanced Properties, please refer to the Changing Advanced Properties section.

  16. Click the Save button.

 

...

Once you create a Web Service Consumer activity on easy parser, you need to pass a valid input request to the Web Service Consumer. To generate the input request as per the Web Service, you can directly load the WS Consumer activity into the Data Mapper. For example, if you have a source data in text format and you want to pass this data to Web Service Consumer as an input request then, you need to perform the following steps:

  • Create a Text Schema
  • Open Data Mapper
  • Load Text Schema at source side
  • Load WS Consumer Activity at target side
  • Select an operation for the Web Service and the XSD type as Input
  • Map the fields to generate a request for the Web Service
Info

If you have the request XML with you then, you can directly pass it to the WS Consumer activity using any Source activity. In this case, you do not have to create any mapping activity.

When you want to pass the response of the Web Service, you need to load the WS Consumer activity at the source side of the Data Mapper. For example, if you want to convert the Web Service response to text format then, you need to perform the following steps:

  • Create a Text Schema
  • Open Data Mapper
  • Load WS Consumer activity at source side
  • Select require operation for the Web Service and select XSD type as Output.
  • Load Text Schema at target side
  • Map the fields to convert the response into the target format
Info

Only by using EasyWSDL parser, you can load WS Consumer activities directly into the Data mapper. If you use WSDL4j parser to create a WS Consumer activity then, you need to create an XML Schema and then load it into the Data Mapper.

 

Steps to Load the Web Consumer Activity into Data Mapper

  1. Create a new data mapping activity for the respective Web Service Consumer activity. While loading the schema, select the WS Consumer tab from the Schema Type column in the Select Schema dialog box (see Figure 311).

    Image Removed
    Figure 311: Select Schema

    Info

    Select the WS Provider tab from the Schema Type column in the Select Schema dialog box, if you want to load WS Provider activity in the Data Mapper.

  2. Click the Load button. This action will display you the Select Operation Dialog box.
  3. Select an operation from the Operation drop-down list. If there is only one operation for this WS Consumer activity, then the Adeptia Suite will show you only that operation as selected (see Figure 312).

    Image Removed

    Figure 312: Select Operation Dialog Box

  4. Select the XSD type from the XSD type drop-down list (see Figure 313).

    Image Removed

    Figure 313: Select Operation Dialog

  5. Click OK to save the changes. This will upload the WS Consumer schema in the Data Mapper (see Figure 314).

Image Removed
Figure 314: Data Mapper

...

This section explains:

...

This section explains how to configure the Adeptia Suite to use WSDL4j parser.
 

Steps to configure Adeptia Suite to use WSDL4j parser

  1. On the Adeptia Suite home page, click the Administer tab and then click at the Setup menu. This action will show you all the options of the Setup menu (see Figure 315).

    Image Removed

    Figure 315: Set Up Menu Options

  2. Select the Application Settings option. This action will show you the Application Settings screen (see Figure 316).

    Image Removed

    Figure 316: Application Settings

  3. Click the Update System Properties link. This action will show you the Update System Properties page.
  4. Click Services to expand the Services hierarchy (see Figure 317).

    Image Removed

    Figure 317: Application Setting Page

  5. Expand Web Service Configuration.
  6. Change the value of the abpm.webservice.consumer.wsdlparser.iswsdl4j property to true (see Figure 318).

    Image Removed

    Figure 318: Web Service Configuration Properties

  7. Click the Save button to save the web service configuration settings.

 

Info

If you want to re-enable the new parser for WS Consumer activity, EasyWSDL parser, then, simply set the value of the abpm.webservice.consumer.wsdlparser.iswsdl4j property to false.

...

This section covers the steps to create Web Service Consumer Activity using wsdl4j parser. Adeptia Suite also supports easy WSDL parser from version 6.0 onwards.
 

Steps to create a Web Service Consumer Activity

...

Go to Configure > Services Web Services and then click Consumer. This action will show you the Manage Consumer screen (see Figure 319).

Image Removed

Figure 319: Manage Consumer Page

...

Check the URI checkbox in the Web Service Definition Location field (see Figure 320).

Image Removed

Figure 320: Locate WSDL

...

Select a consumer type from Consumer Type radio button.

Info

Select SOAP, when you want to access any SOAP-based Web Service.
To know how to create a Web Service Consumer activity to access any RESTful Web Service, refer to the Creating Web Service Consumer activity for RESTful Web Service section.

...

Select the location of URI.

Info

In the URI Location, select:

  • HTTP, if the WSDL file is on a HTTP Site.
  • Local/LAN, if the WSDL file is on a Local/LAN environment.

Click the Browse WSDL button. This action will show you the Upload WSDL File screen (see Figure 321).

Info

If, for the URI Location field, you check the HTTP radio button then skip the steps 8 - 9 and continue from step 10.

...

 

...

Click the Browse button to select the WSDL file. Then click the Upload File button. This action will upload the file and display it in the WSDL File Path (Local/LAN) textbox on the Web Consumer screen (see Figure 322).

Image Removed
Figure 322: Uploaded WSDL File

...

Select the Secure checkbox if the path in the WSDL URL field is secured. Then enter the user ID and password in the User ID and Password field respectively.
 

Info

If, for the URI Location field, you check the Local/Lan radio button then follow steps 8 - 9 and skip step 10.

...

Click the Next button. This action will show you the New Web Consumer screen (see Figure 323).

Image Removed

Figure 323: Select Web Service Operation

...

Select an operation from the Operation(s) dropdown list. This selection will automatically display you the name of the style in the Style Name dropdown list.

Info

When you select an operation then the Style Name field gets its data automatically. There are two types of styles in this field:

  • Document: When a WS Consumer invokes a document style Web service, the consumer typically sends it an entire document, such as a purchase order, rather than a discrete set of parameters. The Web service accepts the entire document, processes it, and may or may not return a result document. In a document style, the input can be read from context or a stream coming from another activity. Similarly, output can be set to context or the WS Consumer activity can generate it as a stream to other activities. In case the output is set to context then, the WS Consumer activity creates a variable in the context with the name as specified in the Output Parameter Name field. The WS Consumer activity then sets the output into that variable. Additionally, you can use the XSD of the Web Service Consumer activity to create an XML schema.
  • rpc: In rpc style, the WS Consumer invokes a Web Service and sends some parameter values to it. The Web Service then executes few methods using these parameter values and sends back the result. In rpc style, the WSDL4j parser creates a variable in the context with a name same as in the Output Parameter Name field and then the output is set into that variable. This style does not generate a stream. 
    In the current example, the Web Service is of doc style.

...

Click the Next button. This action will show you the Web Service Consumer screen (see Figure 324).

Image Removed

Figure 324: Enter Input and Output Parameters

Select a security Policy from the dropdown list if required.

Info

You may also override the security policy activity that is being called within a consumer activity. For this, there is a context variable, securityPolicy. It is accessible via put-context-var action of a process flow designer. For details, refer to the following sections:

To learn about its Advanced Properties, please refer to the Changing Advanced Properties section.|

...

Click the Save button.

 

Info

In case you want to update your existing Web Service Consumer Activity using EasyWSDL parser then please refer to the Updating Existing Web Service Consumer Activity Using EasyWSDL Parser section.

...

Updating WSDL4j Web Service Consumer Activity to Use EasyWSDL Parser

...

Steps to Use EasyWSDL Parser for Existing Web Service Consumer Activity 

  1. On the Adeptia Suite homepage, click the Develop tab.
  2. Go to Services > Web Services and then click Consumer.
  3. Click on the existing activity that you want to parse using EasyWSDL parser.
  4. Check the Move to New Parser (EasyWSDL) checkbox (see Figure 325).

    Image Removed
    Figure 325: Move To EasyWSDL Parser
  5. Follow the steps of the wizard and then click the Save button to save your activity.

Info

The Help link beside the Move to New Parser (EasyWSDL) checkbox provides you with some additional information about the parser.

 

...

Steps to Use Web Service Addressing (WS-Addressing)

  1. To use WS-Addressing, while creating Web Service Consumer activity please expand WS-A addressing properties (see Figure 326).

    Image Removed

    Figure 326: Define WS-Addressing Parameter

  2. Check the Enable WS-A addressing check box and define all the parameters.

...

WS-Addressing Parameters

Variable Name

Must Understand

WSMUSTUNDERSTAND

WS-A Version

WSAVERSION

Action

WSACTION

To

WSTO

Reply To

WSREPLYTO

Reply To Reference Parameters

WSREPLYTOREFERENCEPARAMETERS

Message ID

WSMESSAGEID

From

WSFROM

Fault To

WSFAULTTO

Fault To Reference Parameters

WSFAULTTOREFERNCEPARAMETER

Relates To

WSRELATESTO

Relationship Type

WSRELATIONSHIPTYPE

Info

To override the WS-Addressing parameter, you need to set the value of corresponding variables within the process flow.

 

...

You can use the Web Service Provider activity to publish your web services so that the web service consumers can access it. Once you publish a Web Service provider activity, it will create a WSDL file, which will be available to the Adeptia Suite users. The user can then use this WSDL to invoke the Web Service.
From Adeptia Suite 6.1 onwards, you will get EasyWSDL parser for Web Service Provider activity. This EasyWSDL parser has the following additional benefits:

  • It is more robust than WSDL4j
  • It is more reliable than WSDL4j

...

  • When you use WSDL4j as your WSDL parser, then the process to create any new WS Provider activity will remain the same as earlier.
  • When you use EasyWSDL as your WSDL parser then:
    • Any new WS Provider activity that you create will use EasyWSDL parser.
    • You don't have to create an XML Schema for this Provider activity. You can directly load the WS Provider activity, in the Data Mapper, and select the operation in the Data Mapper.
      To know how to load a WS Provider activity in the Data Mapper, refer to the Loading Web Service Provider in Data Mapper section.
    • You cannot use the Web Service Provider to create an XML Schema.
    • If you edit any existing WS Provider activity in the Adeptia Suite, that you made using an earlier version of the Adeptia Suite then, the Adeptia Suit will use WSDL4j parser to edit it.
Info
  • If you create any WS Provider activity using the WSDL4j parser then, the Adeptia Suite will always use that parser to edit the activity irrespective of the WSDL parser that is currently configured on the Adeptia Suite.
  • Similarly, if you create any WS Provider activity using EasyWSDL parser then, the Adeptia Suite will always use that parser to edit the activity irrespective of the WSDL parser that is currently configured on the Adeptia Suite.

This feature is available in:

Enterprise

Premier

Professional

Express

 

 

...

Creating Web Service Provider activity using EasyWSDL parser

This section explains how to create WS Provider activity, when you configure the Adeptia Suite to use EasyWSDL parser. 

Steps to create Web Service Provider activity using EasyWSDL Parser

...

Go to Services > Web Services and then click Provider. This action will show you the Manage Provider screen (see Figure 327).

Image Removed

Figure 327: Manage Web Service Provider Activity

...

Click the Create New link. This will show you the New Web Service Provider screen.

Image Removed

...

Enter the name and description of the new Web Service Provider activity in the Name and Description textboxes respectively.

Info

In case the Web Services Provider activity contains characters which falls in character set encoding, other than the default character set encoding, then you can change this encoding in the Character Set Encoding textbox. By default, this textbox will display you the character set encoding that you have defined at the application level.

...

Select the type of web service that you want to publish from the Publish Type radio button.

 

Info
  • Select SOAP, when you want to publish a SOAP-based web service.
  • Select REST, when you want to publish a RESTful web service.

To know how to create a Web Service Provider activity to access a RESTful web service, refer to theUsing RESTful Web ServiceCreating RESTful Web Service Provider Activity section.

...

If you want to create this activity by uploading a WSDL file then, select Yes in the Upload WSDL drop-down list. Otherwise, select No. The default value of this drop-down list is No.

Info

Skip step 7 – 11 and continue from step 12 if you select No in the Upload WSDL drop-down list.

...

If WSDL file is referring to another WSDL or XSD file then you can either choose an existing file reference activity from the File References drop-down list or click on the Image Removed button to create a new file reference activity. You can click on the Image Removed button, if you want to update an existing file reference activity.

Info

To know how to create a file reference activity, please refer to the Creating File Reference section.

...

Click the Browse WSDL button and upload the WSDL file that you want to use while creating your Web Service Provider activity. This action will show you the Upload WSDL File screen (see Figure 328).

Image Removed

Figure 328: Upload WSDL

Click the Choose File button, select the WSDL, and then click the Upload File button. This action will upload your WSDL file (see Figure 329).

 

Image Removed

Figure 329: Create Web Service Provider

 

Info

If there is only one service name in your WSDL file then the Adeptia Suite will show that service name as selected. If there are multiple service names in your WSDL file then the Adeptia Suite will show you all the services in a drop-down list options in the Service Name field. In this case, you have to select the service that you want.
When you select the service name, it will then populate the Binding field automatically. This field displays only those bindings, that correspond to the service name, which you will select in the Service Name field. If in the WSDL definition file there is only one binding for any service name then, by default you will see only that binding in the Binding field. However, if there are multiple bindings for a service name then, you will see all the bindings in the drop-down list.

...

Select a mode of configuration from the Configuration Mode drop-down list.

 

Info
  • Configuration Mode can be either: For All Operation: In case you want to select just one process flow to invoke any operation then select this option. However, you can execute the process flow only when you invoke an operation.
  • Per Operation: In case you want to select multiple process flows for invoking different operations then select this option. Here you can also leave any operation unbound. If you invoke any unbound operation then, you will see a "Requested Operation is not implemented" error message.

...

Enter the request service name, by which you want to publish your web service, in the Request Service Name text box (see Figure 330).

Image Removed

Figure 330: Create Web Service Provider

...

Select the SOAP version from the Soap Version drop-down list.

...

Select the process flow, which you want to publish as web service from the Process Flow Name dropdown list.

...

Select an input XML schema from the Input XML Schema dropdown list. This XML Schema will contain the XML that the Web Service provider activity will input.

Select the output XML schema from the Output XML Schema dropdown list.

Info

In case an XML Schema has multiple roots then, click the Select Root button and select a root.

Info

Skip step 12-16 and continue from step 17 if you have selected Yes in the Upload WSDL drop-down list.

...

Enter the input and output variables in the Input Variable and Output Variable textboxes respectively

Info

By default, the request service will be in the services/<folder name>. You can change this location and provide a new location for accessing the web service.

Info

If you want your WS Provider activity to offer a SSL security then check the Enable SSL checkbox.

...

Select the security policy activity from the Security Policy dropdown list if required (see Figure 331).

 

Info

If you want to extract attachments from the request and send it with your response then you must check the Enable Attachment checkbox. For more information on this refer Using Attachments in Web Services section (see Figure 332).

 

Image Removed

 

Figure 332: Create Web Service Provider

Click the Save button.

...

ClientIP: If you want to know the IP address of the clients who are accessing your web service.

WsProviderTypeId: If you want to know the Type Id of your web service provider activity.

...

This section explains how to Load the Web Service Provider Activity into Data Mapper.
 

Steps to Load the Web Service Provider Activity into Data Mapper

  1. Create a new data mapping activity for the respective Web Service Provider activity. While loading the schema, select the WS Provider tab from the Schema Type column in the Select Schema dialog box (see Figure 333).

    Image Removed

    Figure 333: Select Schema

  2. Click the Load button. This action will display you the Select Operation Dialog box.
  3. Select an operation from the Operation drop-down list. If there is only one operation for this WS Provider activity, then the Adeptia Suite will show you only that operation as selected (see Figure 334).

    Image Removed

    Figure 334: Select Operation Dialog Box

  4. Select the XSD type from the XSD type drop-down list (see Figure 335).

    Image Removed

    Figure 335: Select Operation Dialog

  5. Click OK to save the changes. This will upload the WS Provider schema in the Data Mapper (see Figure 336).

Image Removed
Figure 336: Data Mapper

...

This section explains how to create WS Provider activity, when you configure the Adeptia Suite to use WSDL4j parser.

Configuring WSDL4j Parser for Web Service Provider

This section explains how to configure the WSDL4j Parser for Web Service Provider. Adeptia Suite also supports easy WSDL parser from version 6.1 onwards.

Steps to configure WSDL4j Parser for Web Service Provider

  1. On the Adeptia Suite home page, click the Administer tab and then click at the Setup menu. This action will show you all the options of the Setup menu (see Figure 306).

    Image Removed

    Figure 306 : Set Up Menu Options

  2. Select the Application Settings option. This action will show you the Application Settings screen (see Figure 307).

    Image Removed

    Figure 307 : Application Settings

  3. Click the Update System Properties link. This action will show you the Update System Properties page.
  4. Click Services to expand the Services hierarchy (see Figure 308).

    Image Removed
    Figure 308: Application Setting Page

  5. Expand Web Service Configuration.
  6. Change the value of the abpm.webservice.provider.wsdlparser.iswsdl4j property to true (see Figure 316).

    Image Removed

    Figure 309: Web Service Configuration Properties

  7. Click the Save button to save the web service configuration settings.
Info

If you want to re-enable the new parser for WS Provider activity, EasyWSDL parser, then, simply set the value of the abpm.webservice.provider.wsdlparser.iswsdl4j property to false.

 

Steps to create a Web Service Provider Activity

...

Go to Services > Web Services and then click Provider. This action will show you the Manage Provider screen (see Figure 337).

Image Removed

Figure 337: Manage Web Service Provider Activity

...

Enter the name and description of the new Web Service Provider activity in the Name and Description textboxes respectively.

Info

In case the Web Services Provider activity contains characters which falls in character set encoding, other than the default character set encoding, then you can change this encoding in the Character Set Encoding textbox. By default, this textbox will display you the character set encoding that you have defined at the application level.

...

Select the type of web service that you want to publish from the Publish Type radio button.

Info
  1. Select SOAP, when you want to publish a SOAP-based web service.
  2. Select REST, when you want to publish a RESTful web service.

To know how to create a Web Service Provider activity to access a RESTful web service, refer to the Creating RESTful Web Service Provider Activity section.

...

If you want to create this activity by uploading a WSDL file then, select Yes in the Upload WSDL drop-down list. Otherwise, select No. The default value of this drop-down list is No.

Info

Skip step 7 – 12 and continue from step 13 if you select No in the Upload WSDL drop-down list.

...

If you select Yes in the Upload WSDL drop-down list then, you can upload your own WSDL file.

...

Click the Browse WSDL button and upload the WSDL file that you want to use while creating your Web Service Provider activity. This action will show you the Upload WSDL File screen (see Figure 338).

Image Removed

Figure 338: Upload WSDL

...

Select the service name, ports, and port type from the respective drop-down list (see Figure 339). Along with this, you will get a list of operations to select the process flow for those operations.

Image Removed
Figure 339: Create Web Service Provider

Select a mode of configuration from the Configuration Mode drop-down list.

 

Info
  • Configuration Mode can be either: For All Operation: In case you want to select just one process flow to invoke any operation then select this option. However, you can execute the process flow only when you invoke an operation.
  • Per Operation: In case you want to select multiple process flows for invoking different operations then select this option. Here you can also leave any operation unbound. If you invoke any unbound operation then, you will see a "Requested Operation is not implemented" error message.

Enter the request service name, by which you want to publish your web service, in the Request Service Name text box (see Figure 340).

Info

Skip step 12– 16 and continue from step 17 if you select Yes in the Upload WSDL drop-down list.

...

Select the process flow, which you want to publish as web service from the Process Flow Name dropdown list.

Info

By default, the request service will be in the services/<folder name>. You can change this location and provide a new location for accessing the web service.

Info

If you want your WS Provider activity to offer a SSL security then check the Enable SSL checkbox.

...

Select the output XML schema from the Output XML Schema dropdown list.

Info

In case an XML Schema has multiple roots then, click the Select Root button and select a root.

...

Figure 341: Create Web Service Provider

Info

To know how to create a security policy, please refer to the Creating Security Policy for Web Services section.

...

Info

If you want to know the IP address of the clients who are accessing your web service then, you can now do that by accessing the ClientIP variable. This variable is a part of the context info of the process flow, which is published by the Web Service Provider. You can use this variable in scenarios such as - When you want to respond to a client's request as per it's IP. You can achieve this by using the IP address of the client that you can easily get from the ClientIP variable.

In case you want to update your existing Web Service Provider Activity using EasyWSDL parser then please refer to the Updating Existing Web Service Provider Activity Using EasyWSDL Parser section.

Updating WSDL4j Web Service Provider Activity to Use EasyWSDL Parser

...

Steps to Use EasyWSDL Parser for Existing Web Service Provider Activity

  1. On the Adeptia Suite homepage, click the Develop tab.
  2. Go to Services?Web Services and then click Provider.
  3. Click on the existing activity that you want to parse using EasyWSDL parser.
  4. Check the Move to New Parser (EasyWSDL) checkbox (see Figure 342).

    Image Removed
    Figure 342: Move To EasyWSDL Parser

  5. Follow the steps of the wizard and then click the Save button to save your activity.

 

Info

The Help link beside the Move to New Parser (EasyWSDL) checkbox provides you with some additional information about the parser.

 

...

You can use web services to send attachments with your provider or consumer activities. Using Adeptia Suite you can now manipulate these attachments by either storing them on your system or encoding these attachments in either Base64 Binary or Hex Binary encodings.
This chapter covers the following:

...

Multipurpose Internet Mail Extensions (MIME) is an Internet standard that helps extend the capabilities of web services by allowing insertion of images, sounds, and text in a message.
MIME offers the following features to web services are as follows:

  • Support for multiple attachments in a single message
  • Support for non-ASCII characters
  • Support for attachments which may contain executables, audio, images and video files, etc.
  • Support for unlimited message length
  • MIME for Web Services or SOAP with Attachments refers to the method of using Web Services to send and receive files using a combination of SOAP and MIME, primarily over HTTP. Adeptia Suite now supports MIME feature in its web services provider and consumer activities.

...

  1. While creating a web service provider, you need to check the Enable Attachment checkbox (see Figure 343).

    Image Removed

    Figure 343: Enable Attachment Property

  2. If the request has any MIME attachments, then your web service provider stores them in the system.

    Info

    The web service provider stores these attachments at a base location that you can configure by the following steps:

    1. From the Adeptia Suite home page, click the Administer tab.
    2. On the Administer tab, click the Update System Properties link.
    3. On the Update System Properties screen, click Services > Web Service Configuration.
    4. Change the value of the abpm.webservice.metro.soapattachment.location property by giving an absolute path. web/Attachments is the default value.
  3. You can find a list of all the names of the attachments and location of the attachments in the context info of the process flow within these variables:
  • SOAPAttachmentsList variable contains the names of the attachments
  • SOAPAttachmentsLocation variable contains the location of the attachments

...

  1. Check the Enable Attachment checkbox while creating web service provider activity (see Figure 344).

    Image Removed

    Figure 344: Enable Attachment Property

  2. In the process flow designer, create context variable MimeAttachmentFolderPath.
  3. Mention an absolute folder path of the attachments in the MimeAttachmentFolderPath variable.

    Info

    If the location of attachments has both attachments and other folders then, the web service provider would only send the files present in the root folder. It will not recursively scan all the other folders for attachments.

  4. The web service provider would then send its response with embedded attachments.

 

...

  1. Create a context variable Service.<entityName>.enableAttachment in the process flow, and set its value to True/Yes if you want to send the attachment with your request.

    Info

    entityName is the name of Web Service consumer activity used in the process flow.
    Set the value to False/No if you don't want to send attachments with your request.

  2. Mention an absolute folder path of the attachments in the Service.<entityName>.mimeAttachmentFolderPath variable.

    Info

    If the location of attachments has both attachments and other folders then, the web service consumer would only send the files present in the root folder. It will not recursively scan all the other folders for attachments.

  3. The web service consumer would then send its response with embedded attachments.

...

Create a context variable Service.<entityName>.enableAttachment in the process flow, and set its value to True/Yes if you want to receive the attachment with your response.

...

If the response has any MIME attachments, then your web service consumer stores them in the system.

Info

The web service consumer stores these attachments at a base location that you can configure by the following steps:

  1. From the Adeptia Suite home page, click the Administer tab.

  2. On the Administer tab, click the Update System Properties link.

  3. On the Update System Properties screen, click Services > Web Service Configuration.

  4. Change the value of the abpm.webservice.metro.soapattachment.location property by giving an absolute path. web/Attachments is the default value.|

...

  • ConsumerSOAPAttachmentsList variable contains the names of the attachments
  • ConsumerSOAPAttachmentsLocation variable contains the location of the attachments

...

Base64 is a mechanism to enable representing and transferring binary data over mediums that allow only printable characters. The need for Base64 arose from the need to attach binary content to web services like images, videos or arbitrary binary content.
HexBinary is a built-in data type that represents binary data encoded in hexadecimal format.
Adeptia Suite now supports Base64 Binary or Hex Binary encoding in its web services provider and consumer activities.

...

While creating a web service provider, you need to check the Enable Attachment checkbox (see Figure 345).

Image Removed

Figure 345: Enable Attachment Property

...

If the request has any Base64 Binary or Hex Binary attachments, then your web service provider stores them in the system and within the request it replaces the attachments with a cid:uniqueid unique ID.

Info

The web service provider stores these attachments at a base location that you can configure by the following steps:

  1. From the Adeptia Suite home page, click the Administer tab.
  2. On the Administer tab, click the Update System Properties link.
  3. On the Update System Properties screen, click Services > Web Service Configuration.
  4. Change the value of the abpm.webservice.metro.soapattachment.location property by giving an absolute path. web/Attachments is the default value.

...

  • SOAPAttachmentsList variable contains the names of the attachments
  • SOAPAttachmentsLocation variable contains the location of the attachments
Info

The binary data that you extract from a request is encoded only if, your client has not enabled the MTOM. Otherwise, the extracted data is not encoded.

...

  1. Check the Enable Attachment checkbox while creating web service provider activity (see Figure 346).

    Image Removed

    Figure 346: Enable Attachment Property

  2. In the process flow designer, create context variable BinaryAttachmentFolderPath.
  3. Mention an absolute folder path of the attachments in the BinaryAttachmentFolderPath variable.

    Info

    If the location of attachments has both attachments and other folders then, the web service provider would send only files in the root folder. It will not recursively scan all the other folders for attachments.
    Moreover the web service provider would attach files in the response by matching uniqueids with itself.

  4. Map the data to send a Base64 binary or Hex binary attachment with your response. Do the textual mapping by matching the Base64 or Hex binary element with cid:filename. Use this mapping activity in the Process Flow.
  5. The web service provider would then send its response with embedded attachments.

 

...

Create a Service.<entityName>.enableAttachment variable in the process designer of the process flow and set its value to True/Yes to send the attachment with your request.

...

Mention an absolute folder path of the attachments in the Service.<entityName>.binaryAttachmentFolderPath variable.

Info

If the location of attachments has both attachments and other folders then, the web service consumer would send only files in the root folder. It will not recursively scan all the other folders for attachments.

...

Create a Service.<entityName>.enableAttachment variable in the process designer of the process flow and set its value to True/Yes to receive the attachment with your response. 

...

If the response has any Base64 Binary or Hex Binary attachments, then your web service consumer stores them in the system and within the response it replaces the attachments with a cid:uniqueid unique ID.

Info
The web service consumer stores these attachments at a base location that you can configure by the following steps:
  1. From the Adeptia Suite home page, click the Administer tab.
  2. On the Administer tab, click the Update System Properties link.
  3. On the Update System Properties screen, click on Services > Web Service Configuration.
  4. Change the value of the abpm.webservice.metro.soapattachment.location property by giving an absolute path. web/Attachments is the default value.

...

You can find a list of all the names of the attachments and location of the attachments in the context info of the process flow within these variables:

  • ConsumerSOAPAttachmentsList variable contains the names of the attachments
  • ConsumerSOAPAttachmentsLocation variable contains the location of the attachments
Info

MTOM (Message Transmission Optimization Mechanism) is a standard way for transmitting binary data, such as images, PDF files, and MS Word documents that uses SOAP protocol. The MTOM message format allows bit stream compression of binary data. This results in less transmission time as a large chunk of binary data takes up less space than its encoded representation.

 

The Adeptia Suite enables you to use MTOM properties for Web Service Consumer activity to achieve the transmission of binary data through SOAP messages. For better performance you can Check the Enable MTOM checkbox to use the MTOM format in your Web Service Consumer Activity(see Figure 347).

Image Removed   Figure 347: Enable MTOM Property  

The binary data that you extract from a response is encoded only if you have not enabled the MTOM checkbox while creating consumer.  

However, if you have enabled the MTOM checkbox and the Web Service that you are trying to hit, also supports and has MTOM enabled at its end, the data that you extract will not be encoded.

...

Mutual authentication, or two-way authentication, or 2WAY authentication, refers to both server and client authenticating each other in such a way that both are assured of each others' identity.
In a two-way SSL, digital certificates represent the identities of the client and server. The two parties establish the trust upon each other by getting the certificates signed by a mutually trusted certificate authority. The process of exchanging certificates and setting up connection properties is called as the Secure Sockets Layer (SSL) handshake.
The Adeptia Suite supports 2 way SSL, when you are accessing or publishing any web service. You can configure the 2 Way SSL on each activity level.

...

When you want to access a SSL-enabled web service using Web Service Consumer activity, then you have to perform the following tasks:

  • Create a Keystore and import your certificate into it.

    Info

    To know how to create a Keystore and import certificates into it, please refer to the Creating Keystore section.

  • Import the certificate of the Server, which you want to authenticate, within Adeptia Truststore.

    Info

    To know how to create a Trust store and import certificate into it, please refer to the Creating Keystore section.

  • Use this security policy within the Web Service Consumer activity.

    Info

    To know how to create a Web Service Consumer activity, please refer to the Creating Web Service Consumer Activity section.

...

  • When you want to publish a SSL-enabled Web Service using Web Service Provider activity, then you have to perform the following tasks: Create a Keystore.

    Info

    To know how to create a Keystore, please refer to the Creating Keystore section.

  • Import the certificate of the clients, which you want to authenticate, within Adeptia Truststore.

    Info

    To know how to create a Trust store and import certificate into it, please refer to the Creating Keystore section.

  • Now to publish the Web Service through SSL, create a Web Service Provider activity. While creating Web Service provider activity, check the Enable SSL checkbox and select the Port which you have defined in the SslSelectChannelConnector (see Figure 348).

Image Removed
Figure 348: Create Web Service Provider with SSL Enabled

...

Since web services expose crucial business information online, hence their security is critical for the business. You can secure a web service by using Security Policy activity. We recommend you to create an appropriate security policy before you publish your web service using the Web Service Provider activity.
This feature is available in:

Enterprise

Premier

Professionalal

Express

 

...

Go to Services Web Services and then click Security Policy.

This action will show you the Manage Security Policy screen (see Figure 349).

Image Removed

Figure 349: Manage Security Policy

...

Click the CreateNew link. This action will show you the New Security Policy screen (see Figure 350).

Image Removed

Figure 350: New Security Policy

...

Select the type of security policy, that you want to use, from the Security Policy Type radio button.

Info

When you check the WS Consumer radio button, you will see a new category SSL Properties on the New Security Policy screen (see Figure 351).

Image Removed

Figure 351: SSL Properties

To use basic authentication in your security policy activity, expand the Basic AuthenticationProperties area and follow the steps below:

  • Select the Basic Authentication checkbox.
  • Enter the user ID and password in the User ID and Password textboxes respectively. Enter again the password in the Confirm Password textbox (see Figure 352).
Info

In case you select a Security Policy with basic authentication, while creating Web Service Consumer activity, only then you will see an additional Authenticate Preemptively checkbox. Check the Authenticate Preemptively checkbox if you want to send the credentials to a server without any request from it. Do not check the Authenticate Preemptively checkbox if you want to send the credentials upon a server request.

Info

You can override the UserID and Password field defined in security policy activity for authentication. To override you need to define following variables in the process flow context:

  • Service.entityName.userID
  • Service.entityName.password 

Here, entityName is security policy activity name which is used in the web service consumer activity of SOAP type.| 

 

Image Removed
Figure 352: Basic Authentication

  • To use SSL in your security policy activity, expand the SSL Properties area and follow the steps below

    Info

    This option is available only with Web service consumer activity.

  • Check the SSL checkbox.

  • Select the Truststore activity in which you have imported the certificate of the Server.

  • Select the Keystore activity that contains your certificate.

  • Select the Alias Name of the Keystore which you want to pass to the server for authentication.

Info

If you do not select a truststore, then the security policy uses the truststore defined at global level within SSL Configuration.
Similarly, if you do not select the Keystore then the security policy uses the Keystore defined at the global level within SSL Configuration.
To view the global Level SSL Configuration properties, click the Administer tab, go to Setup > Application Settings > Update System Properties > Services > SSL Configuration.

To define message level security (WS-Security) for outgoing message, expand the Outgoing Message Properties area and follow the steps below: (see Figure 353).

...

You can use one or more following options:

  • Signature:
    Signs outgoing message content. To configure signature, check the Signature checkbox. Specify which Keystore to use from the KeyStore dropdown list and define the following property in the respective fields.
Info

To know how to create a Keystore, please refer to the Creating Keystore section.

    • Alias (This should be same as in the Alias field in the Keystore)
    • Include Time Stamp
    • Key Identifier Type (You can use Binary Security TokenIssuer Name Serial NumberSubject Key Identifier, or X509 Certificate)
      • Signature Algorithm (This should be same as in the Key Algorithm field in the Keystore)
      • SignatureCanonicalization
    • Define the parts that you want to sign in the Parts table. Enter the name and its namespace in the Name and Namespace fields respectively. The Parts table allows you to selectively sign only subsets of the message content by specifying the name or namespace of the element (if left empty the Security Policy will sign the entire message).
    • Select whether you want to sign the Content or Element from the Encode dropdown list.
Info

In case you do not define any part then the Security Policy will sign the whole message.

  • Encryption:
    Select the Encryption checkbox to encrypt outgoing message content. Specify which Keystore to use along with the alias/password.
Info

While using encryption, select the keystore with RSA key algorithm only.
To know how to create a Keystore, please refer to the Creating Keystore section.

    • Enter the following property in the respective fields.
      • Alias (This should be same as in Alias field in the Keystore)
      • Key Identifier Type (You can use Binary Security TokenIssuer Name Serial NumberSubject Key Identifier, or X509 Certificate)
      • Symmetric Encoding Algorithm
      • Key Encryption Algorithm
    • Define the parts that you want to encrypt, in the Parts table. Enter the name and its namespace in the Name and Namespace fields respectively.
    • Select whether you want to encrypt the Content or the Element from the Encode dropdown list.
  • User Name Token:
    • Adds a Username Password token to the outgoing message, specify the username and password to use and if you want to add nonce to it. The Password Type dropdown list gives you certain options to serialize your password in the message.
    • To add user name token, check the User Name Token checkbox and define the following properties:
      • User Name
      • Password
      • Confirm Password
      • Token Nonce
      • Add Created
      • Password Type
  • Time Stamp:
    Adds a Timestamp token to the outgoing message with the specified Time To Live value.
    • To add time stamp with the message check the Time Stamp checkbox and enter the time (in seconds) in Time To Live textbox.

...

To define message level security (WS-Security) for incoming message, expand the Incoming Message Properties area and select the Incoming Message checkbox (see Figure 354).

Image Removed
Figure 354: Define Message Level Security for Incoming Message

...

You can use one or more following options:

  • Signature:
    To configure signature, check the Signature checkbox.
    • Select a Keystore from the Signature KeyStore dropdown.

      Info

      To know how to create a Keystore, please refer to the Creating Keystore section.

    • Check the Include Time Stamp checkbox if required.
    • Define the parts that you want to sign, in the Parts table. Enter the name and its namespace in the Name and Namespace fields respectively.
    • Select whether you want to sign the Content or Element from the Encode dropdown list.
Info

In case you do not define any part then the Security Policy will sign the whole message.

  • Encryption:
    • To configure Encription, check the Encription checkbox. Specify which Decryption Keystore to use.
Info

While using encryption, select the keystore with RSA key algorithm only.
To know how to create a Keystore, please refer to the Creating Keystore section.

    • Define the parts that you want to encrypt, in the Parts table. Enter the name and its namespace in the Name and Namespace fields respectively.
    • Select whether you want to encrypt the Content or the Element from the Encode dropdown list.
  • User Name Token:
    To configure User Name Token, check the User Name Token checkbox.
    • Specify the username and password to use.
    • Confirm your password.
    • Check the Token Nonce Required checkbox if you want to add nonce to it.
    • Select a Password Type from the dropdown list.
  • Time Stamp:
    To add time stamp with the message check the Time Stamp checkbox and enter the time (in seconds) in Time To Live textbox.
Info

To learn about Advanced Properties refer to Changing Advanced Properties section.

...

Click the Save button.

Info

If you check the Incoming Message checkbox without specifying Signature Required and Encryption Required properties, the system uses SSL Configuration properties (which is defined in Update System Properties section) by default.

 

...

This section explains how to add SSL SelectChannelSelector in Adeptia Jetty.
 

Steps to add SSLSelectChannelSelector in jetty

...

Add an sslContextFactory within sslContextFactory definition section as shown below.

Code Block
<!-- sslContextFactory definition 
 *To add SslContextFactory( which is used in SslSelectChannelConnector definition)
modify id of SslContextFactory as it should be different from already defined sslContextFactory.
modify KeyStore properties as per the requirement. 
<New id="sslContextFactory2" class="org.eclipse.jetty.http.ssl.SslContextFactory">
<Set name="KeyStore"><Property name="jetty.home" default="." />/etc/jetty/custom.keystore</Set>
<Set name="KeyStorePassword">password</Set>
<Set name="KeyManagerPassword">password</Set>
<Set name="TrustStore"><Property name="jetty.home" default="." />/etc/jetty/custom1.keystore</Set>
<Set name="TrustStorePassword">password</Set>
</New>

...

  1. Path and Name of the keystore file.
  2. Keystore password
  3. Key Manager password
  4. Path and Name of the truststore.
  5. Truststore password

...

Now add the SslSelectChannelConnector within Connector's definition as shown below.

Code Block
<!-- Connector's definition 

 To add SslSelectChannelConnector modify below items:
*modify id as per the declared sslContextFactory(user has to define new sslContextFactory if new keystore for this connector is required) 
*Declaration (refer to the section sslContextFactory definition).
*modify connector name from HttpsConnectorB to the required name.
*modify Port value as per the requirement 

<Item>
<New class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector">
<Arg><Ref id="sslContextFactory2" /></Arg>
<Set name="name">HttpsConnectorB</Set>
<Set name="Port">7443</Set>
<Set name="maxIdleTime">30000</Set>
<!—- If you will set NeedClientAuth property to true it means you have enabled the client authentication for this connector i.e. client will be authenticated for the each request and if you set it to false then it means client will not be authenticated at server side. -->
<Set name="NeedClientAuth">true</Set>
<Set name="Acceptors">2</Set>
<Set name="AcceptQueueSize">100</Set>
</New>
</Item>

...

Enter the following details within the new SslSelectChannelConnector, which you have added.

  1. Define the name of the sslContextFactory, which you have added.

  2. Enter the name of SslSelectChannelConnector.

  3. Enter the port at which you want to publish the Web Service.

  4. If you want to authenticate the client, set the value of NeedClientAuth attribute to true.

Info

If you want to publish more than one Web Service each on different ports, then you have to define SslSelectChannelConnector for each port.

...

.