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.

Creating Web Service Consumer Activity

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

The old WDSL parser (WSDL4j), is still there to provide you backwards compatibility. By default, the Adeptia Suite uses the EasyWSDL parser.
To use the WSDL4j parser, you need to change the abpm.webservice.consumer.wsdlparser.iswsdl4j to true. For details to configure this property, please refer to the Configuring Adeptia Suite to use WSDL4j Parser section.
Following are the key points that you should keep in mind while using the WS Consumer feature:

• 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.

This feature is available in:

Creating Web Service Consumer Activity using EasyWSDL Parser

This section explains how to create WS Consumer activity, when the Adeptia Suite is configured to use EasyWSDL parser. By default the parser is set as EasyWSDL.
 

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).

   

   Figure 305: Consumer Manage Screen

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

   

   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.

   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  button to create a new file reference activity. You can also click on the button, if you want to update an existing file reference activity.

    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).

    

    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).

    

    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 ).

     

    

     

     

    Figure 309: Select binding for Consumer Activity Screen

    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.

    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).

    

    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.

    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:

    • Overriding an activity using put-context-var
    • Creating Security Policy for Web Services 

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

16. Click the Save button.

Loading the Web Service Consumer Activity in Data Mapper

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

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

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).
   

   
   Figure 311: Select Schema

   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).

   

   Figure 312: Select Operation Dialog Box

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

   

   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).

Figure 314: Data Mapper

Creating Web Service Consumer Activity using WSDL4j Parser

This section explains:

• Configuring Adeptia Suite to use WSDL4j parser
• Creating Web Service Consumer activity using WSDL4j

   

Configuring Adeptia Suite to use WSDL4j Parser

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).

   

   Figure 315: Set Up Menu Options

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

   

   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).

   

   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).

   

   Figure 318: Web Service Configuration Properties

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

Creating Web Service Consumer Activity using WSDL4j Parser

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

1. On the Adeptia Suite homepage, click the Develop tab.

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

   

   Figure 319: Manage Consumer Page

3. Click the Create New link. This action will show you the New Web Service Consumer screen.
4. Enter the name of the new WS Consumer activity in the Name field. Then, enter the description for this activity in the Description textbox.

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

   

   Figure 320: Locate WSDL

6. Select a consumer type from Consumer Type radio button.

   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.

7. Select the location of URI.

   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.

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

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

   
   
   Figure 321: Upload WSDL File

    

9. 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).

   
   Figure 322: Uploaded WSDL File

10. 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.
     

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

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

    

    Figure 323: Select Web Service Operation

12. Select the name of service from the Service Name dropdown list.
13. Select a port type from the Port Type dropdown list. A port type can support multiple ports. This selection populates the options in the Ports dropdown list.
14. Select a port for the port type from the Ports dropdown list.

15. 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.

    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.
16. Select an operation from the Operation dropdown list.

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

    

    Figure 324: Enter Input and Output Parameters

18. Select a security Policy from the dropdown list if required.

    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:

    • Overriding an activity using put-context-var
    • Creating Security Policy for Web Services

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

    
    

19. Click the Save button.

Updating WSDL4j Web Service Consumer Activity to Use EasyWSDL Parser

If you want to update your existing WS Consumer activity (created using wsdl4j parser) with the new parser (EasyWSDL Parser) then you can do that by following the steps mentioned below: 

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).

   
   Figure 325: Move To EasyWSDL Parser

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

Using Web Service Addressing

Web Services Addressing or WS-Addressing allows Web Services to communicate addressing information by providing a standard way to include message routing data within the SOAP headers.
Adeptia Suite allows you to use WS-Addressing at the WS Consumer Activity level. To enable it in a WS Consumer activity, you can either dynamically define the message addressing properties or manually enter them while creating the activity.
If you want to manually enter the values, create a WS Consumer activity, expand the WS-Addressing properties, and select the Enable WS-A addressing check box. Note that each parameter of a WS-Addressing property has a corresponding Override checkbox. If you select that checkbox, then the WS Consumer activity will use the values or parameters in the corresponding context process flow and would ignore the parameters or values in the text boxes. However, if you do not select this checkbox then the WS Consumer activity will use the values or parameters of this section for the respective WS Consumer Activity.

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).

   

   Figure 326: Define WS-Addressing Parameter

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

If you want to override WS-Addressing Parameters' values dynamically then you need to check the "Override" checkbox. The following table lists all the WS-A Parameters and their respective context variables.

Table 1: WS-Addressing Parameter and Corresponding Variable

Creating Web Service Provider Activity

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

By default, the Adeptia Suite will use the EasyWSDL parser. However, the WSDL4j parser is still there for backwards compatibility.
To use the WSDL4j parser, you need to change the abpm.webservice.provider.wsdlparser.iswsdl4j to true. For details to configure this property, please refer to the Configuring Adeptia Suite to use WSDL4j Parser section.
Following are the key points that you should keep in mind while using the WS Provider feature:

• 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.

This feature is available in:

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

1. On the Adeptia Suite homepage, click the Develop tab.

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

   

   Figure 327: Manage Web Service Provider Activity

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

   

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

   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.

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

    

   • 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.

6. 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.

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

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

8. 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 button to create a new file reference activity. You can click on the button, if you want to update an existing file reference activity.

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

9. 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).

   

   Figure 328: Upload WSDL

10. 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).

     

    

    Figure 329: Create Web Service Provider

     

    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.

    
    

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

     

    • 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.

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

    

    Figure 330: Create Web Service Provider

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

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

15. 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.

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

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

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

    
    
    Figure 331: Create Web Service Provider

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

    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.

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

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

     

    • To know how to create a security policy, please refer to the Creating Security Policy for Web Services section.
    • To learn about its Advanced Properties, please refer to the Changing Advanced Properties section.

19. 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).

     

    

     

    Figure 332: Create Web Service Provider

    
    

20. Click the Save button.

    The following  context variables are the parts of context info of the process flows, which are published by the Web Service Provider.
    
    You may now access:

    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.

    
    

Loading the Web Service Provider Activity in Data Mapper

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).

   

   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).

   

   Figure 334: Select Operation Dialog Box

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

   

   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).

Figure 336: Data Mapper

Creating Web Service Provider Activity using WSDL4j Parser

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).

   

   Figure 306 : Set Up Menu Options

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

   

   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).

   
   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).

   

   Figure 309: Web Service Configuration Properties

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

Steps to create a Web Service Provider Activity

1. On the Adeptia Suite homepage, click the Develop tab.

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

   

   Figure 337: Manage Web Service Provider Activity

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

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

   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.

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

   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.

6. 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.

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

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

8. 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).

   

   Figure 338: Upload WSDL

9. 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).

10. 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.

    
    Figure 339: Create Web Service Provider

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

     

    • 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.

    
    

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

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

    
    
    Figure 340: Create Web Service Provider

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

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

    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.

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

15. 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.

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

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

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

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

    Figure 341: Create Web Service Provider

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

19. Click the Save button.

Updating WSDL4j Web Service Provider Activity to Use EasyWSDL Parser

If you want to update your existing WS Provider activity (created using wsdl4j parser) with the new parser (EasyWSDL Parser) then you can do that by following the steps mentioned below:
 

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).

   
   Figure 342: Move To EasyWSDL Parser

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

Using Attachments in Web Services

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:

• Using MIME
• Using Base64 Binary and Hex Binary Encoding

Using MIME

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.

Web Service Provider Activity Using MIME

In Adeptia Suite, web service provider activity extracts all the MIME attachments from web service request and send attachments in web service response.
Handling MIME Attachments in Request
When your web service provider activity receives a request that has MIME attachments then, please follow the below steps:

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

   

   Figure 343: Enable Attachment Property

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

   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 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.
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

Sending MIME Attachments in Response
When your web service provider activity is sending response with MIME attachments then, please follow the below steps:

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

   

   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.

   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.

Web Service Consumer Activity Using MIME

In Web Service Consumer activity, send MIME attachments with Web Service request and extract all the attachments in Web Service response.
Sending MIME Attachments in Request
When your web service consumer activity sends a request with MIME attachments then, please follow the below steps:

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.

   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.

   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.

Handling MIME Attachments in Response
When your web service consumer activity receives a response with MIME attachments then, please follow the below steps:

1. 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.

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

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

   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.|

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:

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

Using Base64 Binary and Hex Binary Encoding

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.

Web Service Provider Activity Using Base64 Binary and Hex Binary

In Web Service Provider activity, extract all the Base64 Binary or Hex Binary attachments from Web Service request and send attachments in Web Service response.
Handling Base64 and Hex Binary Attachments in Request
When your web service provider activity receives a request that contains Base 64 and Hex Binary attachments then, please follow the below steps:

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

   

   Figure 345: Enable Attachment Property

   
   

2. 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.

   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 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.
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

Sending Base64 and Hex Binary Attachments in Response
When your web service provider activity is sending response that has Base64 and Hex Binary attachments then, please follow the below steps:

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

   

   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.

   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.

Web Service Consumer Activity Using Base64 Binary and Hex Binary

In Web Service Consumer activity, send Base64 Binary or Hex Binary attachments with Web Service request and extract all the attachments in Web Service response.
Sending Base 64 and Hex Binary Attachments in Request
When your web service consumer activity is sending a request that has Base64 Binary and Hex Binary attachments then, please follow the below steps:

1. 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.

   entityName is the name of the 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>.binaryAttachmentFolderPath variable.

   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.

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

Handling Base 64 and Hex Binary Attachments in Response
When your web service consumer activity receives a response that has Base64 Binary and Hex Binary attachments then, please follow the below steps:

1. 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. 

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

2. 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.

   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.

   
   

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:

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

Using 2 Way SSL in Web Service Communication

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.

Configure 2 way SSL at Service Level in WS Consumer

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.

  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.

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

• Create a Security policy and select the Keystore and the Trust store within SSL Properties.

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

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

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

Configure 2 way SSL at Service Level in WS Provider

• 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.

  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.

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

• Add a connector SSLSelectChannelSelector for jetty.

  To know how to add SSLSelectChannelSelector, please refer to the Adding SSLSelectChannelSelector for jetty 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).

Figure 348: Create Web Service Provider with SSL Enabled

Creating Security Policy Activity for Web Services

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:

Steps to create a Security Policy Activity

1. On the Adeptia Suite homepage, click the Develop tab.

2. Go to Services > Web Services and then click Security Policy.

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

   

   Figure 349: Manage Security Policy

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

   

   Figure 350: New Security Policy

4. Enter the name and description of the new Security Policy in the Name and Description textboxes respectively.

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

   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).

   

   Figure 351: SSL Properties

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

   1. • 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).

      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.

      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.| 

       

      
      Figure 352: Basic Authentication

      
      

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

     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.

   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.

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

   
   
   Figure 353: Define Message Level Security for Outgoing Message

8. 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.

   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 Token, Issuer Name Serial Number, Subject 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.

   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.

   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 Token, Issuer Name Serial Number, Subject 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.

9. 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).

   
   Figure 354: Define Message Level Security for Incoming Message

10. You can use one or more following options:

    • Signature:
      To configure signature, check the Signature checkbox.

      • Select a Keystore from the Signature KeyStore dropdown.

        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.

    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.

    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.

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

11. Click the Save button.

Adding SSLSelectChannelSelector for jetty

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

Steps to add SSLSelectChannelSelector in jetty

1. Go to /ServerKernel/etc/jetty folder and open the Jetty.xml file.

2. Add an sslContextFactory within sslContextFactory definition section as shown below.

   <!-- 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>

3. Define the following details within the new sslContextFactory, which you have defined:
   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

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

   <!-- 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>

5. 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.

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

6. Save the file and restart the kernel and WebRunner.