com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.

Working with Endpoint References

Owned by Former user (Deleted)
Jul 13, 2018
3 min read

An endpoint reference holds information to call a service. The simplest endpoint reference is usually a URL but it can also be much more complex.

In BPEL, endpoint references (EPRs) are modeled as partner link roles. When defining a partner link, two roles that can be defined are myRole and partnerRole:

<partnerLink name="responderPartnerLink" partnerLinkType="test:ResponderPartnerLinkType" myRole="main" partnerRole="responder" initializePartnerRole="yes"/>

Both partnerRole and myRole represent EPRs. So when assigning partner link roles or invoking partners, you are using EPRs behind the scene. 

The following is a sample configuration for securedinvoke.epr.

<wsa:EndpointReference
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.w3schools.com uep_schema.xsd"
        xmlns:wsa="http://www.w3.org/2005/08/addressing"
        xmlns:wsdl11="http://schemas.xmlsoap.org/wsdl/">
   <wsa:Address>https://localhost:9443/services/UserRegistrationService</wsa:Address>
</wsa:EndpointReference>

There are multiple ways you can store EPR file(s).

  1. Package it with the BPEL process. A sample tree structure of the BPEL package is given below.
          In the deploy.xml file, you can specify the file path as follows:
     

    <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config" endpointReference="securedinvoke.epr" />

     

  2. Store in the registry (config or governance registry). You can specify the file path in the deploy.xml file as follows:

    <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config" endpointReference="conf:/securedinvoke.epr" /> OR <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config" endpointReference="gov:/securedinvoke.epr" />

  3. Store in the file system. You can specify the file path relative to the CARBON_HOME as follows in the deploy.xml file: 

    <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config" endpointReference="./../../../../repository/conf/securedinvoke.epr" />

The following is a sample deploy.xml configuration:

<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03" xmlns:sample="http://wso2.org/bps/sample" xmlns:services.core.ndatasource.carbon.wso2.org="http://services.core.ndatasource.carbon.wso2.org">
  <process name="sample:AdminServiceInvokeSample">
	<active>true</active>
	<retired>false</retired>
	<process-events generate="all"/>
	<provide partnerLink="client">
  	<service name="sample:AdminServiceInvokeSample" port="AdminServiceInvokeSamplePort"/>
	</provide>
	<invoke partnerLink="dataSourcePL">
  	<service name="services.core.ndatasource.carbon.wso2.org:NDataSourceAdmin" port="NDataSourceAdminHttpsSoap11Endpoint">
   	 <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config" endpointReference="./../../../../repository/conf/securedinvoke.epr" />
  	</service>
	</invoke>
  </process>
</deploy>

Configuring EPR for accessing basic-auth enabled services

A sample EPR configuration is given below. Add values for ‘authorization-username’ and ‘authorization-password’ to invoke the service which are secured with basic authentication.

<wsa:EndpointReference
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.w3schools.com uep_schema.xsd"
        xmlns:wsa="http://www.w3.org/2005/08/addressing"
        xmlns:wsdl11="http://schemas.xmlsoap.org/wsdl/">
	<wsa:Address>https://localhost:9443/services/UserRegistrationService</wsa:Address>
	<wsa:Metadata>
           <id>SInvokeEPR</id>
           <transport type="http">
      			<authorization-username>admin</authorization-username>
      			<authorization-password>admin</authorization-password>
           </transport>
	</wsa:Metadata>
</wsa:EndpointReference>

Securely storing the password in an EPR file

All WSO2 products, by default, come with a secure vault implementation, which is a modified version of synapse secure vault. It provides capability to securely store sensitive data such as plain-text passwords in configuration files of the WSO2 Carbon platform, such as user-mgt.xml, Carbon.xml, Axis2.xml, registry.xml etc. All WSO2 Carbon-based products inherit the secure vault implementation from the core Carbon platform. For more information, see Carbon Secure Vault Implementation in the WSO2 Administration Guide.

WSO2 Business Process Server provides the feature to securely store sensitive data in unified endpoint reference configuration files, using the Secure Vault functionality. Users can encrypt their passwords using tokens instead of the actual password inside the data service configuration file. The instructions below explain how to secure passwords in a data source configuration.

  1. Run the ciphertool script from the <BPS_HOME>/bin directory.
    • Linux: sh ciphertool.sh -Dconfigure
    • Windows: ciphertool.bat -Dconfigure
  2. To encrypt the plain text using ciphertool, run the ciphertool script again without -Dconfigure option. It asks for the KeyStore Password of the running Carbon instance. The default is wso2carbon.
  3. Provide the plain text value that needs to be encrypted and the tool returns the encrypted text value.
  4. Update the <BPS_HOME>/repository/conf/security/cipher-text.properties file by adding a new alias (any name of your preference) and the encrypted value. E.g., BPELEPR.Password=[admin].
  5. Update the <BPS_HOME>/repository/conf/security/cipher-tool.properties file by uncommenting secret alias (e.g.: BPELEPR.Password) and providing the EPR file name along with the xpath for the authorization-password. E.g., BPELEPR.Password=securedinvoke.epr//EndpointReference/Metadata/transport/authorization-password,false

Multiple secret aliases are supported.

The following is a sample deploy.xml configuration:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<wsa:EndpointReference
    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	xsi:schemaLocation="http://www.w3schools.com uep_schema.xsd"
    	xmlns:wsa="http://www.w3.org/2005/08/addressing"
    	xmlns:wsdl11="http://schemas.xmlsoap.org/wsdl/"
    xmlns:svns="http://org.wso2.securevault/configuration">
	<wsa:Address>https://localhost:9443/services/NDataSourceAdmin/</wsa:Address>
	<wsa:Metadata>
      	<id>SInvokeEPR</id>
      	<transport type="http">
   	 		<authorization-username>admin</authorization-username>
   			<authorization-password svns:secretAlias="BPELEPR.Password">password</authorization-password>
      	</transport>
  	</wsa:Metadata>
</wsa:EndpointReference>
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.