Partner Link
See Also
In the context of BPEL, partner links describe interaction between a BPEL process and external web services. The Partner Link activity defines the role each partner plays in the exchange of conversational messages. Indirectly, by virtue of its reference to a partner link type, a Partner Link activity indicates which port types are implemented by each partner.
Partner Link Elements and Partner Link Type Definitions
The partner link type is a BPEL extension for WSDL. As such, it is defined in a WSDL file, not in a BPEL file. The partner link type creates an association between one or two arbitrary roles and indicates that each role must implement a single port type. By associating a port type with a role, the partner link type defines interaction rules between partners.
Do not confuse the Partner Link elements and partner link type definitions:
- Partner link types and roles are BPEL extensions, which are defined in WSDL files.
- Partner Link elements are BPEL 2.0 elements. They are defined in the BPEL process file. Partner Link elements make reference to partner link type attributes.
Partner link type definitions are prerequisites to a Partner Link element. A Partner Link element can only be defined by referring to a particular partner link type and role which must be defined in the WSDL file.
Ways to Add a Partner Link
You can add a Partner Link to a business process in one of the following ways:
- Drag the Partner Link element from the Palette onto the diagram.
- Drag a WSDL file from the same project in the Projects window onto the diagram.
- Drag a WSDL file from a different project in the Projects window onto the diagram. The IDE automatically retrieves the WSDL file from another project and copies related files to the Partner directory in your project structure.
- Drag a web service node from an EJB project or a Web Application project in the Projects window onto the diagram.
- When you drag a web service node, the BPEL Designer retrieves the WSDL file from the Application Server. To successfully retrieve the WSDL file, the Application Server must be running and the web service project must be deployed.
Using a Partner Link element
To use the Partner Link element:
- In the Design view, add a Partner Link element to the diagram using one of the methods listed above.
The Partner Link Property Editor dialog box appears.
- In the Property Editor dialog box, specify the following:
- Name. Accept the default name or enter an arbitrary name. The name must be unique for the process.
- WSDL File. Select the WSDL file describing external service associated with the Partner Link.
The WSDL file can be pre-selected if you have added the Partner Link element by dragging a WSDL file onto the diagram.
- Select one of the following options to specify the Partner Link Type:
- Use Existing Partner Link Type. If you want to use the partner link type definitions that already exist in the specified WSDL file, select this option and follow the procedure for existing Partner Link Types below.
- Use a Newly Created Partner Link Type. If you want to create a new partner link type definition in the specified WSDL file and use it within this Partner Link element, select this option and follow the procedure for new Partner Link Types as outlined below.
To use an existing Partner Link Type:
- Select the Use Existing Partner Link Type option and select the partner link type from the drop-down list. The My Role and/or Partner Role fields are filled in automatically.
- Click OK.
The IDE modifies the BPEL file with the values you have provided.
- To swap the roles of the business process (My Role) and the partner (Partner Role), click the Swap Roles button.
To add a Partner Link Type to a WSDL file and configure the Partner Link element to use it:
- Select the Use a Newly Created Partner Link Type option.
- Specify the WSDL file in which to add a partner link type. You can do one of the following:
- Add the partner link type to the wrapper WSDL file, as suggested by the IDE in the Create in File field by default. If you choose this option, the IDE will automatically create the wrapper WSDL file in your project structure. The original WSDL file will be imported to the newly created wrapper WSDL file.
- You can use wrapper WSDL files when the original WSDL file is read-only or when you do not want to modify the original WSDL file.
- Add the partner link type to a WSDL file within your project. Click Browse and locate the WSDL file in which to add the partner link type.
- Specify the partner link type name.
- Specify the role for the business process (My Role) and/or the partner role (Partner Role) as follows:
- Select the checkbox that to the role you want to define.
- Specify the role name in the Role Name field.
- Select the Port Type from the drop-down list.
- Click OK.
The IDE adds a new partner link type definition to the WSDL file and modifies the BPEL file with the values you have provided.
- Note that at least one of the roles must be set or the Partner Link will not be configured properly.
Dynamic Addressing
Sometimes you need to communicate with partner services whose endpoints are not known beforehand or you need to change an endpoint reference (EPR) during the process execution. The Dynamic Partner Links feature allows you to dynamically assign an endpoint reference to the partner link. This means you can use one partner link for communication with several web–services as long as these services have the same interface.
Each partne link has abstract information and concrete information defined. While the abstract information describing web-service interface should be static, the concrete access information such as address and port can be discovered and used dynamically.
Note: For successful deployment of the process a partner link should be completely defined. It means that when you deploy the project, the WSDL file for the partner link should contain both the abstract and the concrete information for the partner link defined, including address and port, though later the concrete information can be changed independently from the WSDL file.
Note: The BPEL specification mandates that only the partner EPR can be changed dynamically. In BPEL terms, only the partnerRole of a partnerLink element can have a new value assigned. The myRole value doesn't change after the BPEL has been deployed.
To assign a new EPR to a partner link you can use the standard Assign activity and the BPEL Mapper.
The EPR information can be provided in different ways:
- you can provide it as a literal (type endpoint reference information manually into a literal) and map it to the partner link
- use an incoming message to extract the endpoint address
- use a variable of the Service Reference type
If you use an incoming message, an EPR schema should be defined as a part of the message in WSDL.
To assign the EPR to a partner link, use the message variable.
To assign a new endpoint reference to a partner link from a variable:
- Create a new Assign activity in the process.
- Open the BPEL Mapper
- Iin the target tree on the right, find the partner link to which you want deliver a new concrete part.
- In the source tree, find a variable containing the new endpoint address
The address of the web-service can be defined in terms of different schemas, and the JBI container requires a special data type called ServiceRefType which is a simple wrapper for any endpoint-describing data type.
To wrap your data:
- In the mapper toolbar, choose BPEL > Wrap with Service Reference.
This function is a doXslTranform function that uses a predefined XSL-style sheet.
-
Draw an ingoing connection to the function from your variable. Then draw an outgoing connection to the partner link.
- A new concrete part is assigned to the partner link.
- See Also
- Receive
- Reply
- Invoke
- Adding WSDL and XML Schema Imports
- About the WSDL Editor
- BPEL Designer Palette: Web Service
- About the Design View of the BPEL Designer
Legal Notices