XML Documents

Edit online

In IBM® webMethods B2B, create and define XML documents by referring to an existing document type in IBM webMethods Integration.

The Business documents page displays a list of documents that are available in IBM webMethods B2B. You can:

View the details of the documents, such as the name and type, the last modified date and time stamp, the status, and the number of attributes associated with the document.
Sort documents alphabetically in the ascending or descending order and view the documents in the active state by selecting Hide inactive option.
Search a document from the list by typing characters in the search box. The list displays all documents starting with the characters you type in the search box.

In IBM webMethods B2B, define various document properties and use them when you create an XML document.

Document recognition criteria: Content that an inbound XML document must have for it to be a match for the XML document. Specify one or more criteria listed below:
- The Root tag the document should have.
- The system or public identifier the document should have.
- Identifiers and optionally, the values the document should have. Define the XML Query Language (XQL) queries that IBM webMethods B2B executes to find the nodes and values.
- Pipeline variables (that is, variables inserted into the pipeline by the service that sends the document to IBM webMethods B2B) and optionally, the values the variables should have.
Attribute extraction: System and custom attribute to extract from the document. Define the XQL queries that IBM webMethods B2B executes to extract the attributes. In addition, specify transformations for extracted attribute; for example, you might want to transform an extracted string value into all uppercase characters.
Pre-processing actions: A document can specify one or more of the following actions:
- Verify Digital Signature, ensures the signed body of the document arrived unchanged, and the sender is who it claims to be. IBM webMethods B2B checks the sender by matching the certificate from the digital signature to the certificate in the partner's profile.
- Check for Duplicate Document, checks whether IBM webMethods B2B has already received the document. IBM webMethods B2B saves the results of this check to the pipeline, for you to use the results in the Save Document to Database pre-processing action to save only the unique documents.
- Save Document to Database, saves the document to the IBM webMethods B2B database. For example, save documents to the database when you want to make multiple attempts to deliver documents to partners.
- Enable Processing Rule Routing uses a processing rule to process the document further. You might not want to use a processing rule:
  
  If you want to only persist the document to the IBM webMethods B2B database.
  
  If you want to process the document using a business process instead of a processing rule.

Defining an XML Document that Refers to an Existing Document in IBM webMethods Integration

Edit online

This use case explains how to define an XML document in IBM webMethods B2B that refers to an existing document in a selected project from IBM webMethods Integration.

In this example, define an XML document purchase_order, which is project-aware of the project B2B_Test in IBM webMethods Integration and refers to an existing document docTypeRef_PurchaseOrderType.

Before you begin

Edit online

Ensure that you have:

An existing project in IBM webMethods Integration.
A document that you want to refer to exists in the selected project.

To define an XML document that refers to an existing document

In IBM webMethods B2B go to Documents > Add Document > XML.
Provide the following details:
- Name. Type purchase\_order, a name for the XML document.
- Description. Optional. Provide a brief description for the XML document.
Select the project B2B_Test.
Click Next.
Select the IBM webMethods Integration document type docTypeRef\_PurchaseOrderType.
Specify the root tag identifier, Actions, the root tag name that the inbound document must have.
Optional. Specify the DTD to use.
Click Finish.

The XML document is created, and the document details page displays the following details:

View this XML document in the list of available documents on the Business Documents page.

Next steps

Edit online

Update the XML document, as required, using the Edit Document option.
Use the Edit Document option to update the name, description, project and document type.
Navigate to the respective pages to edit the Identifiers, Attributes, Namespaces, and Options.
Activate the XML document and test it.

Defining an XML Document from a Sample XML Document

Edit online

This use case explains how to define an XML document from a sample XML document.

The use case starts with a sample XML document based on which you want to define an XML document and ends when you successfully create the XML document.

In this example, define an XML document PurchaseOrder, that is project-aware of the project B2B_Test in IBM webMethods Integration and uses a sample XML document PORequest.xml.

Before you begin

Edit online

Ensure that you have:

An existing project in IBM webMethods Integration.
XML document structure (document type, schema, and so on) defined in the system.

To define an XML document from a sample XML document

In IBM webMethods B2B go to Documents > Add Document > XML.
Provide the following details:
- Name. Type PurchaseOrder, a name for the XML document.
- Description. Optional. Provide a brief description for the XML document.
Select the project B2B_Test.
Click Next.
Select No to create an XML document without referring to an existing document type from the selected project.
Select Sample XML document.
Provide the sample XML document by dragging and dropping the required file in the space provided.

Alternatively, browse and select the required file to upload the file.

Note: The sample XML file should have a file size, which is less than or equal to 1 MB.
Click Finish.

The XML document is created, and the document details page appears displaying the following details:

View this XML document in the list of available documents on the Business Documents page.

Next steps

Edit online

After adding the XML document, extract the senderID and receiverIDs for the documents manually, so that they can be recognized by IBM webMethods B2B.

Important: After adding XML documents using DTD or XSD or a sample XML, you must explicitly add the processVersion attribute in the pipeline matching step under Identifiers for each of the documents, so that IBM webMethods B2B can recognize Rosettanet messages.
Activate the XML document and test it.

With this use case, the respective document type is also created on IBM webMethods Integration.

Alternate flow

Edit online

Update the XML document, as required, using the Edit Document option.
Use the Edit Document option to update the name, description, project and document type.
Navigate to the respective pages to edit the Identifiers, Attributes, Namespaces, and Options.

Defining an XML Document by Using an XML Schema

Edit online

This use case explains how to define an XML document from XML schema.

The use case starts when you have an XML schema based on which you want to define an XML document and ends when you successfully create the XML document.

In this example, define an XML document purchaseorder1, that is project-aware of the project B2B_Test in IBM webMethods Integration and uses an XML schema POAccept.xsd.

Before you begin

Edit online

Ensure that you have:

An existing project in IBM webMethods Integration.
XML document structure (document type, schema, and so on) defined in the system.

To define an XML document from an XML schema

In IBM webMethods B2B go to Documents > Add Document > XML.
Specify the following details:
- Name. Type purchaseorder, a name for the XML document.
- Description. Optional. Provide a brief description for the XML document.
Select the project B2B_Test.
Click Next.
Select No to create an XML document without referring to an existing document type from the selected project.
Select XML schema.
Select File as the XML schema source. Provide a URL on which an XML schema source is hosted.
Provide the XML schema file by dragging and dropping the required file in the provided space. Alternatively, either browse for the required file to upload it, or provide the XML schema URL. Ensure that you also have the user credentials to access the URL-hosted schema.

Note: The XML schema file should have a file size, which is less than or equal to 1 MB.
Select the Content model compliance. The content model provides a formal description of the structure and allows the content to be of a complex type. Specify whether IBM webMethods B2B enforces the following model compliance when generating the document type:
- Strict. Generates the document type only if IBM webMethods B2B can represent the content models defined in the XML Schema definition correctly. Document type generation fails if IBM webMethods B2B cannot accurately represent the content models in the source XML Schema definition.
- Lax. Generates the document type even if the content models in the XML schema definition cannot be represented correctly.
- None. Generates the document type that does not necessarily represent or maintain the content models in the source XML Schema definition.
Select Preserve text position. Specifies that the document type generated for a complex type that allows mixed content to preserve the location of text in instance documents. The resulting document type contains a body field after each field and includes a leading body field.
Select Validate schema using Xcerces. IBM webMethods B2B uses the Xerces Java™ parser to validate the XML Schema definition.
Click Next.
In the Select root node section, select the element PurchaseOrderAcceptance that you want to use as the root element for the document type. Select multiple elements by pressing the CTRL key. If IBM webMethods B2B determines that the XML Schema definition is invalid, the Select root node panel displays an error message to that effect. Click Cancel to abandon the attempt to create a document type.
Click Finish. The XML document is created, and the document details page appears displaying the following details: View this XML document in the list of available documents on the Business Documents page.

Next steps

Edit online

After adding the XML document, you must manually extract the senderID and receiverIDs for the documents, so they can be recognized by IBM webMethods B2B.
Important: After adding XML documents using DTD or XSD or a sample XML, you must explicitly add the processVersion attribute in the pipeline matching step under Identifiers for each of the documents, so that IBM webMethods B2B can recognize Rosettanet messages.
Activate the XML document and test it.

With this use case, the respective document type is also created on IBM webMethods Integration.

Alternate Flow

Edit online

Update the XML document, as required, using the Edit Document option.
Use the Edit Document option to update the name, description, project, and doctype.
Navigate to the respective pages to edit the Identifiers, Attributes, Namespaces, and Options.

Defining an XML Document with a DTD

Edit online

This use case explains how to define an XML document with a DTD.

The use case starts when you have either a plain DTD document or a DTD document in a compressed zip, or a URL on which a DTD is hosted based on which you want to define an XML document. The use case ends when you create the XML document.

In this example, define an XML document based on a DTD purchaseorder1, that is project-aware of the project B2B_Test in IBM webMethods Integration and uses a DTD POAccept.DTD.

Before you begin

Edit online

Ensure that you have an existing project in IBM webMethods Integration.

To define an XML document with a DTD

In IBM webMethods B2B go to Documents > Add Document > XML.
Provide the following details:
- Name. Type purchaseorder1, a name for the XML document.
- Description. Optional. Provide a brief description for the XML document.
Select the project B2B_Test.
Click Next.
Select No to create an XML document without referring to an existing document type from the selected project.
Select DTD Document to build the XML document.
Select the method to upload the DTD document. Either use a plain DTD document that is available locally, or a DTD in a compressed format or a URL that hosts the DTD document.

If you upload a compressed DTD document, ensure that you provide the DTD document path along with the file name within the compressed file. For example, if the DTD document is within a several levels of sub folders, specify the exact file path and the filename of the DTD document.

Note: The DTD document or Compressed zip containing DTD document should be less than or equal to 5 MB in size.
Click Next.
Select a root DTD with which you want to create the XML file.
Click Finish.

Next steps

Edit online

After adding the XML document, you must manually extract the senderID and receiverIDs for the documents, so they can be recognized by IBM webMethods B2B.
Important: After adding XML documents using DTD or XSD or a sample XML, you must explicitly add the processVersion attribute in the pipeline matching step under Identifiers for each of the documents, so that IBM webMethods B2B can recognize Rosettanet messages.
Activate the XML document and test it.

With this use case, the respective document type is also created on IBM webMethods Integration.

Alternate flow

Edit online

Update the XML document, as required, using the Edit Document option.
Use the Edit Document option to update the name, description, project, and doctype.
Navigate to the respective pages to edit the Identifiers, Attributes, Namespaces, and Options.

Updating an XML Document

Edit online

Modify or update the following aspects of an XML document:

Status
Description
Options
Properties of documents that have a structure associated with it.

These properties impact the behavior of each node in an inbound document. Any inbound document that deviates from the properties you set for each of the nodes, generates appropriate validation errors in the Course of transaction.

Note: The updates you make to a business document on IBM webMethods B2B are also propagated to the IBM webMethods Integration instance.

To update an XML document

In IBM webMethods B2B, go to Documents.
Select an XML document from the Business Documents page.
Click Edit Document to modify the document name, description, project name, and document type, as required.
Click Update.
Modify the following fields by navigating to respective pages in the document summary section:
- Identifiers: Modify the information for the following identifiers:
  
  Root tag to match the document type
  
  Doctype identifier that inbound documents must have to match the document type
  
  Identifying queries
  
  Pipeline variables that must be present in inbound documents to match the document type
- Attributes: Document attribute values to extract from documents that match this document type.
- Namespaces: Namespace mappings for IBM webMethods B2B to locate the nodes identified by the XQL queries.
- Options: Settings for rule processing, duplicate check, and document persistence.
  
  Enable or Disable Processing Rule Routing
  
  Enable or disable digital signature verification
  
  Check for duplicate document
  
  Persist document option
  
  For details on the fields and their description, see XML Document Properties
Click Update.

The XML document is updated to include the modifications.

Next steps

Edit online

Activate the document and test it.

Testing an XML Document

Edit online

If you have samples of XML documents IBM webMethods B2B processes, test them to determine whether each document:

Matches exactly one XML document. The XML document types are set up correctly for the document.
Does not match any XML document. IBM webMethods B2B considers such a document an unknown document type. Create a document type using the sample document or update an existing document type to identify the document.
Matches more than one XML document. IBM webMethods B2B considers the document as an unknown document type if it cannot determine which document type to use. Update the XML document types so that the document matches exactly one XML document type.

Note:

IBM webMethods B2B does not test documents against disabled document types.
IBM webMethods B2B does not actually process the document you are testing. That is, IBM webMethods B2B does not perform any pre-processing or processing actions on the document.

Before you begin

Edit online

Ensure that the XML document is in active state.

To test an XML document

In IBM webMethods B2B, go to Documents.
On the Business Documents page, click Test Document.
Drag and drop the required .xml file

Alternatively, browse and select the required .xml file.
Click Test XML.

IBM webMethods B2B displays all document types that match the sample document.

Adding RosettaNet PIP Document

Edit online

The RosettaNet organization creates and maintains Partner Interface Processes (PIPs) to provide common business-process definitions for all RosettaNet message exchanges.

Downloading the PIP

Edit online

Visit the RosettaNet website.
Locate the corresponding PIP under the PIP directory that you want to create. For example, to request a purchase order change, use 3A8_RequestPurchaseOrderChange_V01_00_00.zip.
Download the PIP zip folder and extract the files.

Note: Extract the contents of the PIP zip folder when the DTD document does not have dependencies.

The folder contains the PIP and the specification file. The specification file in the PIP folder explains the PIP parameters. For more information about the PIP parameters, see Configuring an RNIF params in IBM webmethods Integration documentation.

Adding a PIP in DTD format

Edit online

To add a PIP in DTD format in IBM webMethods B2B, see Defining an XML Document with a DTD.

XML Document Properties

Edit online

The following sections describe various document properties against which IBM webMethods B2B validates any inbound document. Modify any of these properties, as required.

Identifiers

Edit online

Define XML document types to be general or specific. For example, define an XML document type that recognizes OAG documents, OAG PROCESS_PO_004 documents, or OAG PROCESS_PO_004 documents from a specific sender.

IBM webMethods B2B displays a tree view of the referred IBM webMethods Integration document in the left panel.

Specify at least one criterion for a document to match a document type. In case of multiple criteria, it must match all the identification criteria you specify. If you specify the Root tag and Doctype criteria, IBM webMethods B2B matches inbound XML documents to those criteria first. If these match, IBM webMethods B2B also checks the identifying XQL queries and values, and the pipeline matching. Matching criteria for XQL queries and its values is case-sensitive.


Field	Description
Root tag	Specifies the root element for the document type. It is the value that inbound documents must have in the root tag to match the document type.
Doctype identifier	Specifies the system or public identifier from the DOCTYPE declaration that inbound documents must have to match the document type. For example, to identify a document that has the DOCTYPE declaration , you would type cXML.dtd.
Identifying queries	Specify that certain nodes must be present for inbound documents to match the document type. You can also specify the values those nodes must have. To do so, define identifying XQL queries. For example: The identifying query below specifies that the OrderRequest tag must be present: `/cXML[0]/Request[0]/OrderRequest[0]` The identifying query below specifies that the Identity tag, within the Sender tag > Credential tag, must be present and must evaluate to XYZ Steel Company: `/cXML[0]/Header[0]/Sender[0]/Credential[0]/XYZ Steel Company` Add a new identifier or replace an existing one. To add a new identifier, select a node for which you want to add an identifying query and click Add Identifier. Provide the XPath expression and the value for the expression. Ensure that the length of the XPath is limited to 2,000 characters. Click Add. Click Update to save the modifications. To replace an identifier, for a particular node select an existing identifier and click Replace Identifier. Choose to modify the value and click Replace. The XPath expression of the selected identifier is replaced with that of the selected node. Click Update to save the modifications.
Pipeline matching	Specify pipeline variables that must be present in the inbound documents to match the document type. Criteria for matching inbound documents to the document type are name/value pairs, where values are optional. The pipeline is a IBM webMethods B2B data structure in which input and output values from services of IBM webMethods B2B application are maintained. The pipeline starts with the input to a service and collects inputs and outputs from subsequent services. When a service executes, it has access to all data in the pipeline. If you do not specify a value, the document matches the document type if the pipeline has a variable that matches the specified name, regardless of the variable's value. If you specify a value, the variable must have the specified value. The variables are inserted into the pipeline by the service from IBM webMethods B2B application that sends the document to IBM webMethods B2B. To add a pipeline variable, click Add Pipeline in the Pipeline matching section on the right. In the Create pipeline match dialog box, type the variable name and optionally, the value.

Attributes

Edit online

In the document type, specify the system and custom document attribute values to extract from documents that match this document type. If you want to transform extracted attributes, use built-in or custom transformations. Add a new attribute or replace an existing one.

On the document details page, click Attributes on the left navigation panel.

To add an attribute, select a node in the left panel for which you want to define an XPath query. Click Add To Attributes and provide the following information in the Add extracted attribute dialog box:


Field	Description
XPath expression	IBM webMethods B2B fills in the XQL query for the node. Ensure that the length of the XPath attribute is limited to 2,000 characters.
Attribute	Specifies the required document attribute values to extract from documents that match this document type. Select the required attribute from the list. If the attribute is not available in the list: Click Add attribute. In the Add document attribute dialog box, provide the required details. Click Save. This displays the Add extracted attribute dialog box. Click Add. The newly added attribute is listed in the attributes list. Avoid using characters other than: A-Z, a-z,0-9, _ (underscore), - (hyphen) in the attribute names.
Type	Specifies the type of the attribute selected.
Description	Specifies the description included for the selected attribute.
Required	By default, when IBM webMethods B2B cannot extract an attribute, it continues processing, and, if processing completes successfully, sets the processing status to DONE. It does not log an error to the activity log. If you want IBM webMethods B2B to log an error to the activity log when it cannot extract an attribute, you can designate that attribute as required for extraction. If processing completes successfully, IBM webMethods B2B sets the processing status to DONE W/ERRORS.
Transformation	IBM webMethods B2B can transform extracted attributes before storing them in the IBM webMethods B2B database. If you extract an attribute that has the data type DATETIME or DATETIME LIST, you must identify the date format. Choose a built-in common date and time format or type the format you need using a pattern string based on the `Time Format Syntax` described for the `java.text.SimpleDateFormat` class. IBM webMethods B2B extracts the value of the date and uses it and the pattern you specify to decode the value and convert it to the format that IBM webMethods B2B requires to store the date in the BizDocEnvelope.If you do not provide a date and time format, the default built-in transformation format dd-MM-yyyy HH:mm:Ss is used. If you extract an attribute that has the data type STRING or STRINGLIST, you can transform the string value using one of the built-in transformations below: Uppercase: Transforms the extracted string attribute value to all uppercase. Lowercase: Transforms the extracted string attribute to all lowercase. String Substitution: Substitutes extracted values with a pattern you specify. IBM webMethods B2B uses the java.text.MessageFormat class to perform this transformation.For example, you might specify the pattern Items Ordered: {0}, {1}, {2} , and specify an XQL query for the attribute that extracts this array of values: 0 Cellular phone 1 Belt clip 2 Rapid mobile charger IBM webMethods B2B would store the following for the value of the attribute: Items Ordered: Cellular phone, Belt clip, Rapid mobile charger If you place more arguments in the pattern than there are extracted values, the string stored in the database for the attribute contains the extra arguments. If you specify fewer arguments than there are extracted values, the string contains only the values for the number of arguments. If you extract an attribute that has the data type NUMBER and contains an array of numbers, use transform the array into a single value using one of the built-in transformations as below: Average: Calculates the average value of all the numbers in the array. Minimum: Calculates the smallest number in the array. Maximum: Calculates the largest number in the array. Sum: Calculates the sum of all the numbers in the array. No format: Stores the first value of the array as the value of the attribute. When IBM webMethods B2B extracts a NUMBER or NUMBER LIST from a document, it uses the number parsing behavior of java.lang.Number. For example, if the NUMBER or NUMBER LIST contains the value 100zzz, IBM webMethods B2B interprets the value as 100, instead of displaying an error as it would if the value were zzz100.

To replace an existing attribute, select a node for which you want to replace an attribute. Select an existing attribute from the list and click Replace Attribute. Modify the attribute name and click Replace. The XPath expression of the selected attribute is replaced with that of the selected node. Click Update to save the modifications.

Namespaces

Edit online

If an XML document uses namespaces, the elements in that document might be prefixed with a string. When you create XQL queries to identify elements within the document, the XQL queries must include the prefix. If XML documents use equivalent namespaces but have different prefixes, you must define namespace mappings for IBM webMethods B2B to locate the nodes identified by the XQL queries. Namespace mappings identify all prefixes that identify the same namespace (that is, point to the same URI).

Include a namespace mapping for each prefix and URI combination that you expect to receive in XML documents from the partners. If IBM webMethods B2B receives a document that uses a prefix that is not defined in the namespace mappings table, it performs a literal match of the XQL queries against the document.

Options

Edit online

On the Options page, define the options and actions, as required:


Field	Description
Enable Processing Rule Routing	Enables processing of documents using pre-processing and processing actions defined in a processing rule. If you want to process documents using only pre-processing actions defined in the document type, disable processing rule routing.
Validate document structure	Validates the structure of the inbound document against the available schema. XML Documents. For business documents created using a sample XML, and for those that do not have a corresponding schema available on IBM webMethods Integration, this option is disabled as the structure cannot be validated against the schema. Note: IBM webMethods B2B does not support validation for documents categorized as large documents in the Large Document Threshold property of the Runtime options. IBM webMethods B2B processes large documents with a warning. EDI Documents. This option is available for all EDI documents including the default EDI documents that are available with IBM webMethods B2B.
Verify digital signature	To use this action, the document type must specify extraction of the SignedBody and Signature system attributes, and the signature must be a PKCS#7 detached signature of the signed body. In addition, the profile for each partner whose digital signature you want to verify must specify a certificate. IBM webMethods B2B ensures that the signed body has not changed by verifying the digital signature. To verify that the sender is who it claims to be, IBM webMethods B2B matches the certificate from the digital signature to the certificate in its database for the sender. Note: To verify the digital signature of cXML documents, you must enable the Validate the signed messages option on the Channels > Configuration page.
Check for Duplicate Document	Checks for a document with the same Document ID; the same Document ID and sender; the same document ID, sender, and receiver; or the same document ID, sender, and document type. In the extraction specifications, you must specify extracting the necessary attributes for the option you select. If you want to use a custom service that performs the check based on other attributes, click Select and search or browse for the service.
Save	You must save a document to the database when you want to: Deliver the document using reliable delivery with immediate or scheduled delivery. Pass a document to a business process. Send a document back to the beginning as a new document (for example, because the document did not match any defined document type). This is called resubmitting the document. Send a document back through processing rules (for example, because the document was processed by the wrong rule). This is called reprocessing the document. Choose to save All documents or Only unique documents. Select whether you want to persist just the Content, Attributes, Activity log or all of them in the saved document.

See the Tutorial on Processing XML Document Type With an AS2 Channel for examples.

See the Tutorial on Processing XML Document Type With an HTTP Inbound Channelfor examples.

Accessing XPath nodes

Edit online

All the XPath operators and XPath axes can be used to access the nodes. For the complete list of operators and axes on XPath, see the XML Path Language (XPath) 3.0 standards.

The following is an XML document sample used in the examples:


<PurchaseOrderRequest>
<PurchaseOrder>
<deliverTo>
<PhysicalAddress>
<cityName>
<FreeFormText>Reston VA</FreeFormText>
</cityName>
<addressLine1>
<FreeFormText>IBM</FreeFormText>
</addressLine1>
<addressLine2>
<FreeFormText>11700 Plaza America Drive</FreeFormText>
</addressLine2>
<addressLine3>
<FreeFormText>Reston VA</FreeFormText>
</addressLine3>
<NationalPostalCode>20190</NationalPostalCode>
</PhysicalAddress>
</deliverTo>
<comment>
<FreeFormText>Comments go here</FreeFormText>
</comment>
<packListRequirements>
<FreeFormText>Packing List Requirements</FreeFormText>
</packListRequirements>
<totalCost free="noMonetaryValue">6510</totalCost>
<!-- This is the items array series -->
<!-- Item 1 -->
<ProductLineItem>
<shipFrom>
<GlobalLocationIdentifier>Warehouse 1</GlobalLocationIdentifier>
</shipFrom>
<ProductQuantity>150</ProductQuantity>
<LineNumber>1</LineNumber>
<productUnit>
<ProductPackageDescription>
<ProductIdentification>
<GlobalProductIdentifier>Anvil</GlobalProductIdentifier>
<PartnerProductIdentification>
<GlobalPartnerClassificationCode>5644</GlobalPartnerClassificationCode>
<ProprietaryProductIdentifier>CS-1100</ProprietaryProductIdentifier>
</PartnerProductIdentification>
</ProductIdentification>
</ProductPackageDescription>
</productUnit>
</ProductLineItem>
<!-- Item 2 -->
<ProductLineItem>
<shipFrom>
<GlobalLocationIdentifier>Computer Warehouse 1</GlobalLocationIdentifier>
</shipFrom>
<ProductQuantity>120</ProductQuantity>
<LineNumber>2</LineNumber>
<productUnit>
<ProductPackageDescription>
<ProductIdentification>
<GlobalProductIdentifier>Hammer</GlobalProductIdentifier>
<PartnerProductIdentification>
<GlobalPartnerClassificationCode>5672</GlobalPartnerClassificationCode>
<ProprietaryProductIdentifier>CS-1150</ProprietaryProductIdentifier>
</PartnerProductIdentification>
</ProductIdentification>
</ProductPackageDescription>
</productUnit>
</ProductLineItem>
</PurchaseOrder>
</PurchaseOrderRequest>

The following table lists some path expressions and the result of the expressions based on the sample XML document:


Example String	XPath Results
PurchaseOrder	Selects all nodes with the name PurchaseOrder.
/PurchaseOrder	Selects the root element PurchaseOrder.
PurchaseOrder/deliverTo	Selects the deliverTo element. `<deliverTo> <PhysicalAddress> <cityName> <FreeFormText>Reston VA</FreeFormText> </cityName> <addressLine1> <FreeFormText>IBM</FreeFormText> </addressLine1> <addressLine2> <FreeFormText>11700 Plaza America Drive</FreeFormText> </addressLine2> <addressLine3> <FreeFormText>Reston VA</FreeFormText> </addressLine3> <NationalPostalCode>20190</NationalPostalCode> </PhysicalAddress> </deliverTo>`
//deliverTo	Selects all deliverTo elements in the document.
PurchaseOrder//deliverTo	Selects all book elements that are descendant of the PurchaseOrder element. `<FreeFormText>Reston VA</FreeFormText>`
//@free	Selects all attributes that are named free. `noMonetaryValue`
//ProductLineItem[ProductQuantity>120]/ProductQuantity	Selects the productLineItem only if the productQuantity is greater than 120. `<ProductQuantity>150</ProductQuantity>`
//PurchaseOrder/totalCost \| //ProductLineItem[ProductQuantity>120]/ProductQuantity	Selects all the totalCost AND ProductQuantity, if the ProductQuantity is more than 120. `<result> <totalCost free="noMonetaryValue">6510</totalCost> <ProductQuantity>150</ProductQuantity> <ProductQuantity>120</ProductQuantity> </result>`
//PurchaseOrder/ProductLineItem[last()]	Selects the last ProductLineItem element that is the child of the PurchaseOrder element. <ProductLineItem> <shipFrom> <GlobalLocationIdentifier>Computer Warehouse 1</GlobalLocationIdentifier> </shipFrom> <ProductQuantity>120</ProductQuantity> <LineNumber>2</LineNumber> <productUnit> <ProductPackageDescription> <ProductIdentification> <GlobalProductIdentifier>Hammer</GlobalProductIdentifier> <PartnerProductIdentification> <GlobalPartnerClassificationCode>5672</GlobalPartnerClassificationCode> <ProprietaryProductIdentifier>CS-1150</ProprietaryProductIdentifier> </PartnerProductIdentification> </ProductIdentification> </ProductPackageDescription> </productUnit> </ProductLineItem>
*	(Wildcard) Matches any element node.
@*	(Wildcard) Matches any attribute node.
node()	(Wildcard) Matches any node of any kind.
/PurchaseOrder/*	Selects all the child element nodes of the PurchaseOrder element.
//*	Selects all elements in the document.
//totalCost[@]*	Selects all title elements which have at least one attribute of any kind. `<totalCost free="noMonetaryValue">6510</totalCost>`

Document Attributes

Edit online

Document attributes identify specific content in the documents when they pass through the network. This specific content in the document may be of your interest in the document. For example, a purchase order number or the account number of a purchaser. You can write specific logic to process a document with a certain purchase order after you extract the attributes of your interest in the document.

The following are a few reasons to extract document attributes:

To use extracted attributes as a criterion for using a particular processing rule. For example, if you want to use one processing rule if the sender is Partner A and another processing rule if the sender is Partner B, you would extract the system attribute SenderID. Or if you want to use a particular processing rule when the receiver is Partner C® and the total order amount is greater than $10,000, you will extract the system attribute ReceiverID and the custom attribute Total_Order_Amount.
To perform certain processing actions that require extracted attributes. For example, if you want to deliver a document to the receiver partner, you would extract the system attribute ReceiverID. If you want to verify the digital signature of an XML document, you would extract the system attributes SignedBody and Signature.
If you want to pass extracted attributes for specific type of analysis. For example, if you want to generate a report on the purchase order quantity for a particular sender from a particular receiver, and classify them as platinum, gold, and silver partners, you would extract the custom attribute PO_Quantity and the system attributes SenderID and ReceiverID and write a business logic to further categorize them.

System Attributes

Edit online

System attributes are the document attributes that IBM webMethods B2B owns. The system attributes are:


System Attribute	Description
Sender ID	Identification of the sender of a document.
Receiver ID	Identification of the receiver of a document.
Document ID	Identification of the document.
User Status	The status that you or a partner associates with the document.
Conversation ID	Identification within a document that associates this document with other documents in the same business process (or conversation of documents).
Signed Body	Portion of a document that contains data that is digitally signed.
Signature	Portion of a document that contains the digital signature of the document.

Custom Attributes

Edit online

Custom Attributes are attributes that you define to identify any other content that you are interested in extracting from the documents. For example, to extract the purchase order number from documents, you might define a document attribute named PO_Number. To extract the total amount of a purchase order, you might define a document attribute named Total_Order_Amount.

Creating Custom Document Attributes

Edit online

Create custom attributes for all the types of documents you expect to receive; attributes are not associated with a specific document type. Later, when you define the document types or add an extended criteria for a rule, you would specify the attributes to extract and to use as criteria.

To create a custom document attribute

In IBM webMethods B2B, navigate to Business Documents > Document Attributes and click Add Document Attribute.
Provide a unique name for the document attribute and optionally, a description. There are certain words you must avoid while creating custom attributes because they might be a part of system attributes, database columns, to name a few. Few words that you must avoid include DocID, DocTimestamp, TypeName, SenderID, SenderCorp, SenderUnit, ReceiverID, ReceiverCorp, ReceiverUnit, RoutingStatus, UserStatus, NativeID, GroupID, ConversationID, Comments, SenderProfileGroup, ReceiverProfileGroup, DocTypeID, and NS Name.
Specify the attributes' Data type. Select one of the following Data types:
- Datetime.
- Datetime List
- Number
- Number List
- String
- String List
Set the status to enabled if you want the attribute to be in Active state. The attribute is by default set to be in the active status. Set the status as inactive and change the status to active at a later point of time by using the Edit () option for the respective document attribute.
Enable the Save option to save the attribute to the database. Save is enabled by default.
Click Add. The custom attribute is created and listed in the Document attributes list. Avoid using characters other than: A-Z, a-z,0-9, _ (underscore), - (hyphen) in attribute the names.

These document attributes are used later when you define document types as a criterion to extract the documents. Modify the Document attribute details or change the status of a document attribute by using the Edit ( icon ) option for the respective attribute.

See the Custom Attribute Tutorial for examples.

Note: The name of the custom attribute cannot be $duplicate as it is a parameter name.

RNIF Attribute Behaviors

Edit online

When you receive an HTTP header with the prefix x-RN- for an inbound RNIF message, IBM webMethods B2B creates a document attribute. You can view this RNIF-specific attribute in the attribute tab of the Transactions page. The RNIF-specific custom attribute is case sensitive.

Using Extracted Attributes as Extended Criteria in an Existing Processing Rule

Edit online

Summary

Edit online

You can use the extracted attributes as extended criteria in processing rules to apply specific logic to specific attributes in a business document using specific processing rules. The use case begins when you have an attribute in a document that requires special routing using processing rules. The use case ends when you have routed the document successfully using the intended processing rule.

Before you begin

Edit online

Ensure that you have added the document from which you want to extract the attribute.
Ensure that you have a processing rule that takes necessary processing action.

Basic flow

Edit online

To extract attributes from a document:

In IBM webMethods B2B, go to Documents and click on the document for which you want to extract attributes.
Go to Attributes.
In the left-side document tree view, select the attribute you want to extract and click Add to Attribute on the right-side panel.

In the Add extracted attribute dialog box, specify the following details:


Fields	Values
XPath expression	The complete XPath expression.
Attribute	Select an attribute either from the list or add one by clicking Add attribute. To add an attribute, specify the following details: Name. Name of the attribute. Data type. Data type of the attribute. Description. A short description of the attribute. Status. Status of the attribute. The possible values are active or inactive. Save. Save the attribute to the instance.
Required	Specify if the attribute value must be mandatorily present in the inbound business document.
Transformation	Specify if a transformation function must be applied to the attribute. The transformations you can apply depend on the data type of the attribute.

Click Add.
In the Attributes page, click Update.

To use the extracted attribute as extended criteria in a processing rule:

In IBM webMethods B2B, go to Rules and select the rule to which you want to add the extended criteria.
In the Extended criteria page, click Add Extended Criteria.

In the Add extracted attribute dialog box, specify the following details:


Fields	Values
Attribute	Select the attribute that you want the processing rule to match with the inbound document.
Data type	Select the data type of the value associated with the attribute.
Operator	Select the match criteria. The operator you can use depends on the data type of the attribute.
Value	Specify the value to which the attribute must be a match.

Click Add.
In the Extended criteria page, click Update.

EDI Attribute Behaviors

Edit online

If there is code in the XPath of an EDI attribute, for example, /ST/RIC/RIC01/code, then the code list validator is applied.
For a record or a composite, if the value of the Max Repeat property is greater than 1, then the XPath contains an array representation - [0]. For example, /ST/TRN[0]/TRN01, TRN[0] represents an array.
If you extract an attribute which has a code in the XPath, then changing the validator property results in a scenario where the attribute is extracted. Similarly, if you change the validator property to code list validator, the attribute is not extracted.

Next steps

Edit online

See the Course of transaction to check if the inbound document was processed by the correct processing rule after matching the extended criteria.