This chapter explains how to configure and design ePM and Enterprise Designer for use with ebXML Protocol Manager and ebXML.
This chapter explains the configuration parameters required in ePM for ebXML Protocol Manager Projects and their operation with ebXML. You can configure these parameter values for ebXML Protocol Manager using the eXchange ePM interface.
Chapter 5, Implementation Scenario explains a sample business scenario with Projects containing specific parameters already set and values already configured correctly in ePM. The ebXML Protocol Manager CD-ROM contains the files that make up this sample scenario.
You must use ePM to set configuration parameters for your ebXML Protocol Manager Projects’ Trading Partners (TPs). Entering the correct values in ePM allows these TPs to operate correctly with eXchange, ebXML Protocol Manager, and ebXML.
The eXchange ePM tool allows you to create and enable TPs for your ebXML Protocol Manager eXchange Projects.
In eXchange, each TP contains information identifying the values for the messaging, enveloping, and/or transport parameters to be used for sending and receiving B2B information.
ePM contains the following types of parameters:
General eXchange parameters common to all protocol managers
ebXML Protocol Manager-specific parameters present only for this particular application
See Configuring TPs for a complete explanation of parameter types.
To create and enable TPs you can do the following operations using ePM:
For complete information on how to do these operations in ePM, see the eXchange Integrator User’s Guide. Also, Run-time Steps contains a sample scenario with specific examples of TPs set up in ePM.
The following sections provide basic instructions on how to use ePM:
The rest of this section provides a general summary of how to access ePM, as well as use it with TPs for ebXML Protocol Manager Projects.
Before you can access ePM for a Project, make sure that, using Enterprise Designer, you have created and activated the eXchange Project Deployment Profiles, including any for the necessary B2B hosts.
After you have ensured these conditions have been met, you can use your Web browser to access ePM. By default, you can access ePM using a predefined URL, for example:
http://localhost:12000/epm |
If access to ePM has been set up using a different URL, consult your system administrator for this URL.
A binding is an association of metadata parameters with a particular set of values you define, using ePM. This metadata can be for either XDCs or IDCs.
The top of the Delivery Channels (XDCs) subtab in ePM lists all bindings currently defined for the current TP’s XDCs.
In the case of XDCs, the transport parameters are those specified in a transport attribute definition (TAD). The packaging (messaging) parameters are those specified in a message attribute definition (MAD).
Access an XDC and create a binding to it.
Import a signature certificate and encryption key, if necessary.
Using certificates and encryption keys in ebXML Protocol Manager is done in the same way for all eXchange protocol managers. For complete information, see the eXchange Integrator User’s Guide .
The top of the Internal Delivery Channels subtab in ePM lists all bindings currently defined for the TP’s IDCs.
In the case of IDCs, the transport parameters are those specified in a TAD. The use of IDCs is optional.
To create the bindings for IDCs you must:
Optionally, you can also:
Add a new binding for your IDC.
To correctly use ebXML Protocol Manager and eXchange, you must understand the concepts and features explained in this section. For a quick reference that provides definitions of features, such as TADs, MADs, IDCs, and XDCs, see the Glossary.
To use ebXML Protocol Manager, you must create and activate one or more TPs. You must also create a new Messaging Service binding based on one of the Messaging Services shown on the ePM window.
You can also find the Messaging Service as the bottom leaf of the ePM Explorer pane’s tree (on the left), under the messaging attributes definition, standard or custom, with which it is associated.
When you are finished, all the new elements you have created appear in this tree, on the ePM Explorer pane.
For details on these components and operations, see the eXchange Integrator User’s Guide. Also, see the sample scenario in Run-time Steps.
After you have set up and activated your TPs, you must configure them for ebXML and your current system. Each set of specific configurations you assign to a TP make up its profile. TP configuration parameters include the following settings:
Properties: Under this tab, you supply values for the necessary eXchange parameters not ebXML-specific, but needed by eXchange. These parameters are basic eXchange properties and enable the essential eXchange operation of its Projects.
Under other tabs, you find parameters that allow you to supply values for the following types of eXchange and ebXML Protocol Manager-specific configuration settings that define:
Delivery Channels: Under this subtab, you supply XDC values for the ToPartner and FromPartner transport attributes, as well as the ToPartner and FromPartner packaging attributes.
Internal Delivery Channels: Under this subtab, you supply values for the ToPartner and FromPartner transport attributes for each IDC.
Messaging Actions: Under this tab, you supply values for each of the messaging actions (inbound and outbound).
The ePM user interface refers to XDCs under tabs and headings named Delivery Channels .
Importing and Configuring TPs in ePM explains a sample scenario with specific examples of how to configure parameters for an individual TP using ePM.
After you have configured each TP, you must activate it then check for its successful activation. See TP Activation for details.
The rest of this chapter explains in detail how to configure each ePM parameter setting for ebXML Protocol Manager’s TPs, summarized under the types shown in the previous list. For more information, including information on the various tabs/subtabs, what they contain, and how to navigate through them, see the eXchange Integrator User’s Guide.
This section describes the ebXML Protocol Manager’s properties configuration used to set basic eXchange parameters. For an example of how these settings appear in the ePM user interface.
These configuration parameters define basic eXchange settings. See the eXchange Integrator User’s Guide for information on these parameters.
This section describes how to configure ebXML Protocol Manager’s bindings for XDCs. You set up and define these bindings by supplying values for the ToPartner transport attributes, the FromPartner transport attributes, and the combined To/FromPartner packaging attributes.
This section explains in detail how to configure ePM’s ebXML-specific parameters. You can find the Delivery Channels (XDCs) subtab example shown under the Components tab.
The ePM user interface refers to XDCs under tabs called Delivery Channels .
These configuration parameters define settings that allow ebXML Protocol Manager to deliver messages to TPs. Their categories are:
These parameters allow you to define general eXchange settings. See the eXchange Integrator User’s Guide for information on these parameters.
These parameters allow you to supply information needed to transport data to the TP. Find these parameters under the ToPartner Transport subtab.
For a complete description of how to enter these parameters for both ToPartner Transport and FromPartner Transport parameters, seeXDC Parameters.
An endpoint specifies the logical address of where messages can be received. The all- purpose end point is used to designate the receipt address of all ebXML messages.
A valid URL, according to the syntax given under XDC Parameters; required.
None
Specifies whether the communication between the message service handler (MSH) servers is synchronous or asynchronous. When set to true, the MSH response message is returned on the same HTTP connection as the inbound request, with an appropriate HTTP response code.
This parameter is not required and is not used in the current release of ebXML Protocol Manager. However, it is provided for compatibility with previous releases.
Ext Attribute SyncReplyMode replaces this parameter in the current release, since ebXML requires a string (for example, None or mshSignalsOnly) and not a Boolean value.
Select true, false, or None; not required.
false
Specifies whether the message is tracked using Enterprise Manager’s Message Tracker. Choosing true enables the Message Tracker.
Select true, false, or None; not required.
false
Allows you to enter the destination URL for the current TP.
A valid URL according to the syntax given under XDC Parameters; required.
None
Allows you to enter any needed message headers and/or values that may be required by the current TP to reach its destination.
Valid message header names and/or values; not required.
None
These parameters allow you to supply information needed to transport data from the TP. See ToPartner Transport for an explanation of these parameters. Find these parameters under the FromPartner Transport tab.
These parameters allow you to define the packaging for data being transported to the TP. Find these parameters under the ToPartner Packaging tab. .
The initial set of parameters before SOAP Media Type are eXchange parameters common to all protocol managers. See the eXchange Integrator User’s Guide for information on these parameters.
Specifies the Simple Object Access Protocol (SOAP) media type. In accordance with the SOAP specification, the multipurpose Internet mail extension (MIME) media type of the SOAP message has the value text/xml.
SOAP media type means the content type for SOAP with Attach, which is multipart and related.
Multipart/Related; required.
Multipart/Related
Provides the sender’s requirements for message encryption using the digital-envelope (DIGENV) method. Digital enveloping is a procedure in which the message is encrypted by symmetrical encryption (using a shared secret key), and the secret key is sent to the message recipient encrypted, along with the recipient’s public key.
Select http://www.w3.org/2001/04/xmlenc#, SMIME2.0, or SMIME3.0; not required.
http://www.w3.org/2001/04/xmlenc#
Identifies the technology used to digitally sign a message. This parameter has a single implied version attribute whose value is a string that identifies the version of the specified technology.
Select XMLDSIG; not required.
XMLDSIG
Identifies the algorithm used to compute the value of the digital signature.
Select http://www.w3.org/2000/09/xmldsig#dsa-sha1, http://www.w3.org/2000/09/xmldsig#rsa-sha1, or http://www.w3.org/2000/09/xmldsig#hmac-sha1; not required.
http://www.w3.org/2000/09/xmldsig#dsa-sha1
Identifies the algorithm used to compute the digest of the message being signed.
Select http://www.w3.org/2000/09/xmldsig#sha1; not required.
http://www.w3.org/2000/09/xmldsig#sha1
Identifies the canonicalization method applied to the data to be signed.
Select http://www.w3.org/TR/2001/REC-xml-c14n-20010315 or http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments; not required.
http://www.w3.org/TR/2001/REC-xml-c14n-20010315
Identifies the encryption algorithm to be used.
Select DES3; not required.
DES3
Specifies the XML digital signature type to be used (see http://www.w3.org/TR/xmldsig-core/).
Select Enveloped, Enveloping, Detached, or SoapEnveloped; not required.
SoapEnveloped
Designates how the signed attribute within the AckRequested element in the SOAP message header is set.
Select Always, Never, or perMessage; not required.
None
When ebXML Protocol Manager sends an encrypted but unsigned message to a TP then gets a signed acknowledgment from the TP, the system cannot verify the signature and logs an error.
Allows you to designate whether the AckRequested element within the SOAP message header is operating.
The value true requests an acknowledgment for each message. Setting it to false disables this feature.
true or false; not required.
false
Requesting acknowledgments per message depends on the following configuration parameters in ePM:
Send Acknowledgments: Provided in ePM by eXchange.
Ack Request is Per Message: ebXML-specific.
If the Ack Request is Per Message value is true, regardless of what is specified in the Send Acknowledgments parameter, the system uses the eXchange setting provided at run-time for outbound messages, that is, the setting under EX_INTERNAL.
If the Ack Request is Per Message value is false, the system checks the value set under Send Acknowledgments. If Send Acknowledgments is true, the system checks for negative acknowledgments. If this value is false, the system ignores negative acknowledgments.
Allows you to designate whether the DuplicateElimination element within the SOAP message header is operating.
If you set this parameter to true, the system keeps each message from being duplicated. Setting it to false disables this feature.
true or false; not required.
false
Eliminating duplicates per message depends on the following configuration parameters in ePM:
Check For Duplicates: Provided in ePM by eXchange.
Duplicate Elimination is Per Message: ebXML-specific.
If the Duplicate Elimination is Per Message value is true, regardless of what is specified in the Check For Duplicates parameter, the system uses the eXchange setting provided at run-time for outbound messages, that is, the setting under EX_INTERNAL.
If the Duplicate Elimination is Per Message value is false, the system checks the value set under Check For Duplicates. If Check For Duplicates is true, the system checks for duplicates. If this value is false, the system ignores duplicates.
Allows you to specify the current message’s final destination. By using toPartyMSH, you make the receiving party the final destination.
Values are listed in the drop-down menu.
Select urn:oasis:names:tc:ebxml-msg:actor:toPartyMSH; required.
None
Specifies the mode of the reply to the current message.
Select None or mshSignalsOnly; required.
None
Specifies the language in which the description, errors, and so on, are sent out. Refer to the appropriate ebXML documentation on their Web site for details.
A valid string supplied by the user; required.
en-us (English, U.S.)
These parameters allow you to define the packaging for data being transported from the TP. Find these parameters under the FromPartner Packaging tab. .
The initial set of parameters before Digital Envelope Protocol are eXchange parameters common to all protocol managers. See the eXchange Integrator User’s Guide for information on these parameters.
Provides the sender’s requirements for message encryption using the digital-envelope (DIGENV) method. Digital enveloping is a procedure in which the message is encrypted by symmetrical encryption (using a shared secret key), and the secret key is sent to the message recipient encrypted, along with the recipient’s public key.
Select http://www.w3.org/2001/04/xmlenc#, SMIME2.0, or SMIME3.0; not required.
http://www.w3.org/2001/04/xmlenc#
Identifies the technology used to digitally sign a message. This parameter has a single implied version attribute whose value is a string that identifies the version of the specified technology.
Select XMLDSIG; not required.
XMLDSIG
Specifies the XML digital signature type to be used (for more information, see http://www.w3.org/TR/xmldsig-core/).
Select Enveloped, Enveloping, Detached, or SoapEnveloped; not required.
SoapEnveloped
Designates how the signed attribute within the AckRequested element in the SOAP message header is set.
Select Always, Never, or Per Message; not required.
None
When a signed acknowledgment is received from a TP and its associated outbound request message is not signed, ebXML Protocol Manager is unable to verify the signature and logs an error.
Allows you to designate whether the AckRequested element within the SOAP message header is operating.
If you set this parameter to true, the system requests an acknowledgment for each message. Setting it to false disables this feature (see Additional Information).
true or false; not required.
false
Allows you to designate whether the DuplicateElimination element within the SOAP message header is operating.
If you set this parameter to true, the system keeps each message from being duplicated. Setting it to false disables this feature (see Additional Information).
true or false; not required.
false
Allows you to specify the current message’s final destination. By using toPartyMSH, you make the receiving party the final destination.
Values are listed in the drop-down menu.
Select urn:oasis:names:tc:ebxml-msg:actor:toPartyMSH; required.
None
Specifies the mode of the reply to the current message.
Select None or mshSignalsOnly; required.
None
Specifies the language in which the description, errors, and so on, are sent out. Refer to the ebXML documentation on their Web site for details.
A valid string supplied by the user; required.
en-us (English, U.S.)
No ebXML-specific parameter configuration for certificates is required. You must import them. See Configuring Companies’ Cryptographic Features for details.
This section describes how to configure ebXML Protocol Manager’s bindings for IDCs. You set up and define these bindings by supplying values for the ToPartner and FromPartner transport attributes for each IDC used by the B2B host.
These configuration parameters are used by the B2B host, and their categories are:
The parameters under this tab allow you to define the sender transport attributes for individual IDC bindings used by the B2B host.
See the eXchange Integrator User’s Guide for an explanation of IDC configuration properties for sender and receiver transport. Under Internal Delivery Channels, select the Transport Name , as appropriate, for example JMS .
The parameters under this tab allow you to define the receiver transport attributes for individual IDC bindings used by the B2B host. Set these parameters in the same way as you do those for the sender transport channels. For details on how to set these parameters, see Sender Transport.
For an example of how the parameters appear in the ePM user interface.
No ebXML-specific parameter configuration is required. For information on configuring enveloping channels, see the appropriate user’s guide for the enveloping protocol you are using.
This section describes how to configure ebXML Protocol Manager’s messaging actions under the ePM Messaging Service Configuration. These settings control messaging actions (inbound and outbound) for the ebXML MAD.
Many of the explanations of these parameters refer to the ebXML Message Service Specification, version 2.0. To find this specification, see the following ebXML Web site:
These configuration parameters define settings that allow ebXML Protocol Manager to set up, control, and order the sending and receiving of messages. These setting categories are:
This section explains in detail how to configure ePM’s ebXML-specific parameters.
When you first click the Messaging Actions tab, each action appears collapsed as a separate line within a bar. The individual parameters for an action appear when you click the action’s plus sign (+) and expand it.
The individual Messaging Actions you see in ePM reflect those created for the current B2B host in Enterprise Designer. messaging actions in the sample scenario are specific to that scenario. The messaging actions you create depend on your system setup and configuration.
These MAD parameters allow you to define messaging actions for outbound messages. For an example of how the parameters appear in the ePM user interface for ebXML Protocol Manager.
The initial set of parameters (before Service Type; see Service Type) are eXchange settings common to all protocol managers. See the eXchange Integrator User’s Guide for information on how to set them, including how to set up messaging actions as either inbound or outbound.
Use this parameter when the parties sending and receiving the message know how to interpret the value of the Service element. The two parties may use the value of the Type attribute to assist the interpretation.
A valid string supplied by the user; not required.
None
Associates the B2B host with a specific role in the business Collaboration, such as a “buyer.”
A valid string supplied by the user; not required.
None
Associates a TP with a specific role in the business Collaboration, such as a “seller.”
A valid string supplied by the user; not required.
None
The PartyID element provides an identifier for the B2B host. The value of the PartyID element is any string that provides a unique identifier. If this value is not a URN, the HostPartyID type must be provided.
A valid string supplied by the user; required.
None
The PartyID element provides an identifier for the B2B host. The type of the PartyID element provides a scope or namespace for the content of the PartyID element.
A valid string supplied by the user; not required.
None
The PartyId element provides an identifier for a TP. The value of the PartyID element is any string that provides a unique identifier. If this value is not a URN, the PartnerPartyID type must be provided.
A valid string supplied by the user; required.
None
The PartyId element provides an identifier for a TP. The type of the PartyID element provides a scope or namespace for the content of the PartyID element.
A valid string supplied by the user; not required.
None
Not yet implemented; the parameter is reserved for future use and is ignored in the current release.
This parameter is part of a planned Message Sequencing feature and indicates the sequence with which a receiving MSH must process the message. The value entered is the start number for sequencing messages.
A valid string supplied by the user; not required.
None
Used to specify a unique, identifying label for each envelope, referred to as the content ID. This parameter is mandatory and must be a global universal identification (GUID).
For details, see the request for comments (RFC) document 2392, Section 2, on the following Web site:
http://www.ietf.org/rfc/rfc2392.txt
A valid GUID identifying the content ID; required.
Envelope
A URI designating the content-location of the MIME body part of an envelope object. Specify this parameter (URI) when the content/payload is not a package along with the message, but instead is referenced using the URI location.
A valid string supplied by the user; not required.
None
Specifies the transfer encoding, for example, base64, to be used for the SOAP envelope. It is recommended that you set this value.
If the message is in a different character format than the one you specify, or if transfer encoding is not specified, the message may become corrupted during data transport. See RFC 2045, Section 6.1, on the following Web site:
http://www.ietf.org/rfc/rfc2045.txt
If an entity is the type “multipart” the content transfer encoding is not permitted to have any value other than 7bit, 8bit, or binary. See RFC 2045, Section 6.4, on the previous Web site.
The output of base64 encoding confirms to the charset US-ASCII. See RFC 2045, Section 6.2, on the previous Web site.
Valid values are 7bit, 8bit, binary, quoted-printable, base64, ietf-token, and x-token, and the parameter entries are not case-sensitive; not required.
Although this parameter is not required, it is recommended.
7bit
Allows for the specification of additional MIME parameters for the envelope, which are in conformance with the MIME (RFC 2045) specification.
See RFC 2045 on the following Web site:
http://www.ietf.org/rfc/rfc2045.txt
Implementations may ignore any MIME header not defined in the ebXML Message Service Specification, version 2.0 (see the ebXML Web site). For example, an implementation could include content-length in a message. However, a recipient of a message with content-length could ignore it.
A valid string supplied by the user; not required.
boundary=MIME_boundary, type=text/xml, start=Envelope
Specifies the MIME content type to be used for the envelope.
Must either be text/xml or application/xml; required
text/xml
Identifies whether the role of the party sending and/or receiving the message is authorized.
fromAuthorizedRole or toAuthorizedRole; not required.
None
When set to true, specifies that the envelope is digitally signed.
true or false; required.
None
Specifies the URI that designates the algorithm to be performed when creating or validating a signature.
You must enter the following value:
http://www.w3.org/2000/09/xmldsig#enveloped-signature |
For more information see the ebXML Message Service Specification, version 2.0, Section 4.1.3 (see the ebXML Web site).
http://www.w3.org/2000/09/xmldsig#enveloped-signature; required.
Same as above
Enter this parameter value for use in conjunction with the Sign Transforms XPath value, to exclude other elements within the SOAP envelope.
You must enter the following value:
http://www.w3.org/TR/1999/REC-xpath-19991116 |
For more information see the ebXML Message Service Specification, version 2.0, Section 4.1.3 (see the ebXML Web site).
http://www.w3.org/TR/1999/REC-xpath-19991116; required.
Same as above
Specifies the XPath expression to be used with the transform element.
You must enter this value as shown below:
not(ancestor-or-self::node()[@soap:actor=’urn:oasis:names:tc:ebxml- msg:actor:nextMSH’] | ancestor-or-self::node()[@soap:actor=’http:// schemas.xmlsoap.org/soap/actor/next’] ) |
For more information see the ebXML Message Service Specification, version 2.0, Section 4.1.3 (see the ebXML Web site).
not(ancestor-or-self::node()[@soap:actor=’urn:oasis:names:tc:ebxml-msg:actor:nextMSH’] | ancestor-or-self::node()[@soap:actor=’http://schemas.xmlsoap.org/soap/actor/next’] ); required.
Same as above
Specifies the URI that designates the algorithm to be performed when canonicalizing the payload’s XML (if necessary).
When used, you must enter this value as shown below:
http://www.w3.org/TR/2001/REC-xml-c14n-20010315 |
http://www.w3.org/TR/2001/REC-xml-c14n-20010315; not required
None
Allows you to specify a unique, identifying name for each payload. For more information, see Envelope ContentID.
A valid string supplied by the user; not required.
None
A URI designating the content-location of the MIME body part of the payload object.
A valid URI supplied by the user; not required.
None
Specifies the transfer encoding, for example, base64, to be used for the payload.
If the message is in a different character format than the one you specify, or if transfer encoding is not specified, the message may become corrupted during data transport. See RFC 2045, Section 6.1, on the following Web site:
http://www.ietf.org/rfc/rfc2045.txt
If an entity is the type “multipart” the content transfer encoding is not permitted to have any value other than 7bit, 8bit, or binary. See RFC 2045, Section 6.4, on the previous Web site.
The output of base64 encoding confirms to the charset US-ASCII. See RFC 2045, Section 6.2, on the previous Web site.
Valid values are 7bit, 8bit, binary, quoted-printable, base64, ietf-token, and x-token, and the parameter entries are not case-sensitive; not required.
None
Allows for the specification of additional MIME parameters for the payload, which are in conformity with the MIME (RFC 2045) specifications.
Implementations may ignore any MIME header not defined in the ebXML Message Service Specification, version 2.0 (see the ebXML Web site). For example, an implementation could include content-length in a message. However, a recipient of a message with content-length could ignore it.
A valid string supplied by the user; not required.
None
Specifies the MIME content-type to be used for the payload.
A valid string supplied by the user; not required.
None
Identifies whether the role of the party sending and/or receiving the message is authorized.
fromAuthorizedRole or toAuthorizedRole; not required.
None
When set to true, specifies that the payload is digitally signed.
true or false; not required.
false
Specifies the URI that designates the algorithm to be performed when creating or validating a signature.
A valid URI string supplied by the user; not required.
None
Used in conjunction with the Sign Transforms XPath parameter to exclude elements within the payload.
A valid string supplied by the user; not required.
None
Specifies whether the current payload is encrypted.
true or false; not required.
false
Allows you to specify transformations you want to be executed on the current payload, before encryption is applied to it. This parameter only applies to XML types of payloads.
A valid XML string supplied by the user; not required.
None
Allows you to specify the XPath to be executed on the current payload.
A valid XPath expression supplied by the user; not required.
None
The parameters for any additional payloads ( Payload2 , Payload3 , and so on), if present, are the same as those for Payload1 , and their values are set in the same way.
These MAD parameters allow you to define messaging actions for inbound messages. For an example of how the parameters appear in the ePM user interface.
The initial set of parameters (before Service Type; see Service Type) are eXchange parameters common to all protocol managers. See the eXchange Integrator User’s Guide for information on these parameters.
The rest of these parameters operate in the same way as those for the outbound. For details on their operation, settings, and values, see Outbound.