Step 8: Synchronize the Publishable Document Types
5. Working with Publishable Document Types
Introduction . . . 56
Creating Publishable Document Types . . . 56
Setting Publication Properties . . . 65
Modifying Publishable Document Types . . . 70
Deleting Publishable Document Types . . . 72
Synchronizing Publishable Document Types . . . 74
Importing and Overwriting References . . . 84
Testing Publishable Document Types . . . 85
5 Working with Publishable Document Types
Introduction
A publishable document type is a named schema‐like definition that describes the structure and publication properties of a particular kind of document. Essentially, a publishable document type is an IS document type with specified publication properties such as storage type and time‐to‐live.
In an integration solution that uses the publish‐and‐subscribe model, services publish instances of publishable document types, and triggers subscribe to publishable document types. A trigger specifies a service that the Integration Server invokes to process the document. For example, you might create a publishable document type named EmpRec that describes the layout of an employee record. You might create a trigger that specifies that the Integration Server should invoke the addEmployeeRecord service when instances of the EmpRec are received. When a service or adapter notification publishes a document of type EmpRec, that document would be queued for the subscribers of document type EmpRec. The Integration Server would pass the document to and invoke the
addEmployeeRecord service.
In a publication environment that includes a Broker, each publishable document type is associated with a Broker document type. Developer provides tools that you can use to ensure that these two document types remain synchronized.
When you build an integration solution that uses publication and subscription, you need to create the publishable document types before you create triggers, services that process documents, and services that publish documents.
Creating Publishable Document Types
One of the first steps in building an integration solution that uses the publish‐and‐
subscribe model is to create and define publishable document types. Once you create publishable document types, you or other developers can subscribe to those publishable document types by creating triggers.
You can create publishable document types by doing the following:
Making an existing IS document type publishable. For information about creating an IS document type, see the webMethods Developer User’s Guide.
Creating a new document type based on an existing Broker document type
The following sections provide more information about creating publishable document types.
Tip! You can distribute the publishable document types that you create to other developers through package replication. For more information, see “Step 4: Make the Publishable Document Types Available” on page 42 and the “Managing Packages” in the webMethods Integration Server Administrator’s Guide.
5 Working with Publishable Document Types
Making an Existing IS Document Type Publishable
You can make an existing IS document type publishable by setting publication properties for the document type. Properties that you can set include: specifying whether instances of the publishable document type should be saved in memory (volatile storage) or saved on disk (guaranteed storage) during processing, and specifying how long instances of the publishable document type should remain on the Broker once they are published.
If the Integration Server on which you have a session is connected to a Broker, when you make an IS document type publishable, the Integration Server automatically creates a Broker document type. The Integration Server automatically assigns the Broker document type a name. This name corresponds to the following format:
wm::is::folderName::documentTypeName. If a document type with this name already exists on the Broker, the Integration Server appends “_1” to the Broker document type name.
For example, if you make the IS document type employee.employeeInfo publishable, the Integration Server creates the Broker document type wm::is::employee::employeeInfo.
However, if a developer using another Integration Server created a Broker document type for an identically named IS document type, the Integration Server assigns the new Broker document type the name wm::is::employee::employeeInfo_1.
If the Integration Server on which you have a session is not connected to a Broker, the publishable document types that you create can be used only in local publishes. That is, instances of the publishable document types can only be published and subscribed to with in the same Integration Server. (Local publishes do not involve a Broker.) Later, when the Integration Server is connected to a Broker, you can create a Broker document type for the publishable document type by pushing the document type to the Broker during synchronization.
1 In the Navigation panel of Developer, open the IS document type that you want to make publishable.
Important! If you want to generate an associated Broker document type at the same time you make the IS document type publishable, make sure that a Broker is configured and the Integration Server on which you are working is connected to it.
For more information about configuring a connection between the Integration Server and the Broker, see “Configuring the Server” in the webMethods Integration Server Administrator’s Guide.
Note: You can only make an IS document type publishable if you own the lock on the IS document type and you have write permission to the IS document type. For information about locking elements and access permissions (ACLs), see the webMethods Developer User’s Guide.
To make an existing IS document type publishable
5 Working with Publishable Document Types
3 Next to the Storage type property, select the storage method to use for instances of this publishable document type.
For more information about selecting a storage type, see “Selecting a Document Storage Type” on page 65.
4 Next to the Discard property, select one of the following to indicate how long instances of this publishable document type remain in the trigger client queue before the Broker discards them.
d
5 On the File menu, click Save to save your changes. Developer displays beside the document type name in the Navigation panel to indicate it is a publishable document type.
Notes:
In the Properties panel, the Broker doc type property displays the name of the
corresponding document type created on the Broker. Or, if you are not connected to a Name” on page 62.
When you make a document type publishable, the Integration Server adds an envelope field (_env) to the document type automatically. When a document is Select... To...
Volatile Specify that instances of this publishable document type are volatile. Volatile documents are stored in memory.
Guaranteed Specify that instances of this publishable document type are guaranteed. Guaranteed documents are stored on disk.
Important! For documents published to the Broker, the storage type assigned to a document can be overridden by the storage type assigned to the client queue on the Broker. For more information, see “Document Storage Versus Client Queue Storage” on page 66.
Select... To...
False Specify that the Broker should never discard instances of this publishable document type.
True Specify that the Broker should discard instances of this publishable document type after the specified time elapses.
In the fields next to Time to live specify the time‐to‐live value and time units.
5 Working with Publishable Document Types
published, the Integration Server and the Broker populate this field with metadata about the document. For more information about this field, see “About the Envelope Field” on page 64.
Once a publishable document type corresponds to an associated Broker document type, you need to make sure that the document types remain in sync. That is, changes in one document type must be made to the associated document type. You can update one document type with changes in the other by synchronizing them. For information about synchronizing document types, see “Synchronizing Publishable Document Types” on page 74.
Creating a Publishable Document Type from a Broker Document Type
If the Integration Server to which you are connected is connected to a Broker, you can elements, see “Importing and Overwriting References” on page 84.
Important! The Broker prohibits the use of certain field names, for example, Java keywords, @, *, and names containing white spaces or punctuation. If you make a
5 Working with Publishable Document Types
See the webMethods Integration Server Administrator’s Guide for information about
configuring the Broker. See the webMethods Developer User’s Guide for information about locking elements and access permissions (ACLs).
1 On the File menu, click New.
2 Select Document Type and click Next.
3 In the New Document Type dialog box, do the following:
a In the list next to Folder, select the folder in which you want to save the document type.
b In the Name field, type a name for the IS document type using a combination of letters, numbers, and/or the underscore character. For information about naming restrictions, see the webMethods Developer User’s Guide.
c Click Next.
4 Select Broker Document Type, and click Next. Developer opens the New Document Type dialog box.
Important! If you do not select the Overwrite existing elements when importing referenced elements check box and the Broker document type references an element with the same name as an existing Integration Server element, Developer will not create the publishable document type.
Important! If you choose to overwrite existing elements with new elements, keep in mind that dependents of the overwritten elements will be affected. For example, suppose the address document type defined the input signature of a flow service deliverOrder. Overwriting the address document type might break the deliverOrder flow service and any other services that invoked deliverOrder.
To create a publishable document type from an existing Broker document type
5 Working with Publishable Document Types
5 In the New Document Type dialog box, do the following:
a In the Broker Namespace field, select the Broker document type from which you want to create an IS document type. The Broker Namespace field lists all of the Broker document types on the Broker territory to which the Integration Server is connected.
b If you want to replace existing elements in the Navigation panel with identically named elements referenced by the Broker document type, select the Overwrite existing elements when importing referenced elements check box.
6 Click Finish. Developer automatically refreshes the Navigation panel and displays beside the document type name to indicate it is a publishable document type.
Notes:
You can associate only one publishable document type with a given Broker document type. If you try to create a publishable document type from a Broker document type that is already associated with a publishable document type on your Integration Server, Developer displays an error message.
In the Properties panel, the Broker doc type property displays the name of the Broker document type used to create the publishable document type. Or, if you are not connected to a Broker, this field displays “Publishable Locally Only”. You cannot edit the contents of this field. For more information about the contents of this field, see
“About the Associated Broker Document Type Name” on page 62.
To create a Broker document type for a publishable document type that is publishable locally only, push the publishable document type to the Broker during
synchronization. For more information about synchronizing, see “Synchronizing Publishable Document Types” on page 74.
The publishable document type you create from a Broker document type has the same publication properties as the source Broker document type
Once a publishable document type has an associated Broker document type, you need to make sure that the document types remain in sync. That is, changes in one document type must be made to the associated document type. You can update one document type with changes in the other by synchronizing them. For information about synchronizing document types, see “Synchronizing Publishable Document Types” on page 74.
Important! Overwriting the existing elements completely replaces the existing element with the content of the referenced element. Any elements on the Integration Server that depend on the replaced element, such as flow services, IS document types, and specifications, might be affected. For more
information about overwriting existing elements, see “Importing and Overwriting References” on page 84.
5 Working with Publishable Document Types
About the Associated Broker Document Type Name
For a document type, the contents of the Broker doc type property can indicate the following:
Whether or not the document type is publishable.
Whether the publishable document type was created from a Broker document type that was itself created from an IS document type.
Whether the publishable document type was created from a Broker document type created in an earlier version of a webMethods component.
Whether instances of the publishable document type can be used in local publishes only. If the publishable document type can be used only in local publishes, there is no corresponding Broker document type.
The following table lists and describes the possible contents of the Broker doc type property.
Broker doc type property Description
wm::is::folderName::documentTypeName The name of the Broker document type that corresponds to the publishable document type.
The wm::is prefix indicates that the Broker
document type was created from an IS document type. (Either the current document type or an IS document type created and made publishable on another Integration Server.) This prefix does not specify which Integration Server the source IS document type is located on.
On the Broker, all document types created from an IS document type are located in the is folder, which is a subfolder of the wm folder. The folderName::documentTypeName portion of the name further identifies where the document type is located on the Broker.
Example:
wm::is::customerSync::Customer::updateCustomer Indicates the Broker document type
updateCustomer is located in the following series of folders wm::is::customerSync::Customer.
5 Working with Publishable Document Types
folderName::documentTypeName The name of the Broker document type that corresponds to the publishable document type.
The absence of the wm::is prefix indicates that the publishable document type was generated from a Broker document type created with an earlier version of a webMethods component.
Example:
Customer::getCustomer
Indicates the Broker document type getCustomer is located in the Customer:: folder.
Publishable Locally Only Indicates that instances of the publishable document type can be used in local publishes only. This publishable document type does not have a corresponding Broker document type.
When you made this document type publishable, the Integration Server was not connected to a Broker. See “Configuring the Server” in the webMethods Integration Server Administrator’s Guide for information about connecting the Integration Server to the Broker.
Note: If you want instances of this publishable document type to be published to the Broker, you need to create a Broker document type for this publishable document type. When the Integration Server is connected to a Broker, you can create the Broker document type by pushing the
publishable document type to the Broker during synchronization. For more information about synchronizing, see “Synchronizing Publishable Document Types” on page 74.
Not Publishable Indicates that this IS document type is not publishable. For information about making an IS document type publishable, see “Making a Publishable Document Type Unpublishable” on page 71.
Broker doc type property Description
5 Working with Publishable Document Types
About the Envelope Field
All publishable document types contain an envelope (_env) field. This field is a document reference to the pub:publish:envelope document type. The envelope is much like a header in an email message. The pub:publish:envelope document type defines the content and
structure of the envelope that accompanies the published document. The envelope records information such as the sender’s address, the time the document was sent, sequence numbers, and other useful information for routing and control.
Because the _env field is needed for publication, Developer controls the usage of the _env field in the following ways:
You cannot insert an _env field in a document type. Developer automatically inserts the _env field as the last field in the document type when you make the document type publishable.
You cannot copy and paste the _env field from one document type to another. You can copy and paste this field to the Input/Output tab or into a specification.
You cannot move, rename, cut, or delete the _env field from a document type.
Developer automatically removes the _env field when you make a document type unpublishable.
The _env field is always the last field in a publishable document type.
For more information about the _env field and the contents of the pub:publish:envelope document type, see the webMethods Integration Server Built‐In Services Reference.
About Adapter Notifications and Publishable Document Types
Adapter notifications determine whether an event has occurred on the adapterʹs resource
Each adapter notification has an associated publishable document type . When you create an adapter notification in Developer, the Integration Server automatically
Note: If an IS document type contains a field named _env, you need to delete that field before you can make the IS document type publishable.
5 Working with Publishable Document Types
The adapter notification publishable document type is directly tied to its associated adapter notification. In fact, you can only modify the publishable document type by modifying the adapter notification. The Integration Server automatically propagates the changes from the adapter notification to the publishable document type. You cannot edit the adapter notification publishable document type directly.
When working in the Navigation panel, Developer treats an adapter notification and its publishable document type as a single unit. If you perform an action on the adapter notification Developer performs the same action on the publishable document type. For example, if you rename the adapter notification, Developer automatically renames the publishable document type. If you move, cut, copy, or paste the adapter notification Developer moves, cuts, copies, or pastes the publishable document type.
For information about how to create and modify adapter notifications, see the appropriate adapter user’s guide.
Setting Publication Properties
When you select a publishable document type in the Navigation panel, its properties are displayed in the Properties panel. For each publishable document type, you can select a storage type, set a time‐to‐live value, and specify whether Integration Server validates published instances of the document type. The following sections provide more information about these properties.
Selecting a Document Storage Type
For a publishable document type, you can set the storage type to determine how the Integration Server and Broker store instances of this document. The storage type also determines how quickly the document moves through the webMethods system. You can select one of the following storage types:
Volatile storage specifies that instances of the publishable document type are stored in memory. Volatile documents move through the webMethods system more quickly than guaranteed documents because resources do not return acknowledgements for volatile documents. (An acknowledgement indicates that the receiving resource successfully stored or processed the document and instructs the sending resource to remove its copy of the document from storage.) However, if a volatile document is located on a resource that shuts down, the volatile document is not recovered when the resource restarts.
The Integration Server provides at‐most‐once processing for volatile documents. That Note: Changing a Publication property causes the publishable document type to be out
The Integration Server provides at‐most‐once processing for volatile documents. That Note: Changing a Publication property causes the publishable document type to be out