Integration Server 10.15 | Built-In Services Reference Guide | Utils Folder | Summary of Elements in this Folder | pub.utils.messaging:syncDocTypesToUM
 
pub.utils.messaging:syncDocTypesToUM
WmPublic. Synchronizes one or more publishable document types with the associated provider definition (channel) on Universal Messaging. For each publishable document type with an encoding type of protocol buffers, the service:
*Creates an updated protocol buffer definition.
*Compiles the updated definition into an updated protocol buffer descriptor.
*Sends the updated protocol buffer descriptor to Universal Messaging.
This is different frompub.publish:syncToProvider which synchronizes the existing protocol buffer descriptor with Universal Messaging.
Input Parameters
reportOnly
java.lang.Boolean Optional. Indicates whether the service updates and synchronizes the protocol buffer descriptors with Universal Messaging and returns a summary of the changes or if the service returns only a summary without making any changes. Set to:
*true to return a summary of the publishable document types for which the service would successfully and unsuccessfully update the protocol buffer descriptor, including the errors and warnings that would be encountered. The service does not update any protocol buffer descriptors. This is the default.
*false to update the protocol buffer descriptor for the selected document types and synchronize the protocol buffer descriptor with the associated channel on Universal Messaging. The service returns a summary of the changes.
backupPackages
java.lang.Boolean Optional. Indicates whether the service creates a package archive for each package affected by this service prior to creating a new protocol buffer definition for the publishable document types. Set to:
*true to create an archive for each package that contains a publishable document type that will be updated by this service. The archive will be named packageName.zip_timeStamp and placed in the following directory: Integration Server_directory \instances\instance_name\replicate\archive. This is the default.
*false to skip creating an archive of each affected package before making updates.
Important:Software AG recommends that you set backupPackages to true when reportOnly is set to false if you have not taken other measures to back up the packages containing the publishable document types to be synchronized using the pub.utils.messaging:syncDocTypesToUM service. After the service executes successfully, restoring from a backup file is the only way to revert a change made by the service.
packageNames
String List Optional. Name of the packages containing the publishable document types that you want to synchronize. The packageNames and documentTypesNames input parameters are mutually exclusive. If you specify a value for both parameters, the service fails with an exception. If you do not specify a value for either, the service updates publishable document types that use the protocol buffer encoding type in all packages that do not start with the letters "wm" in any case combination.
documentTypeNames
String List Optional. Fully qualified names of the publishable document types that you want to synchronize.
Output Parameters
affectedPackages
Document Conditional. An IData containing key=value pairs that identify the packages impacted by the synchronization and the name of the archive created for the package. The service returns an archive name only if reportOnly is set to false and backupPackages is set to true. The archive will be named packageName.zip_timeStamp and will be located in the following directory: Integration Server_directory \instances\\replicate\archive.The service returns affectedPackages only if the service finds at least one publishable document type to update and synchronize.
failedPackages
Document List Conditional. List of the packages that could not be archived. If Integration Server cannot create a package archive for any of the affected packages, the service ends with an error and nothing is migrated.
The service attempts to archive a package only when backupPackages is set to true .
The service returns the failedPackages parameter only if one of the following occurs:
*The backupPackages input parameter is set to true and an error prevented the service from archiving at least one package.
*A package listed in the packageNames input parameter did not contain any publishable document types to update.
Key
Description
package
String Name of the package that the service could not archive because of an error.
errors
String Text of the error message that caused package archiving to fail.
updatedDocumentTypes
Document List Conditional. List of the publishable document types updated by the service. The service returns the updatedDocumentTypes parameter only if the service updated one or more publishable document types.
Key
Description
package
String Name of the package containing the updated publishable document type.
name
String Fully qualified name of the updated publishable document type.
skippedDocumentTypes
Document List Conditional. List of the publishable document types that were not updated because there were no changes to make. Some reasons the service might skip a publishable document type include, but are not limited to:
*The publishable document type uses a Broker connection alias.
*The publishable document type does not use protocol buffers as the encoding type.
*Values were not specified for either the packageNames or the documentTypeNames input and Integration Server found publishable document types in packages whose names started with the letters "wm" in any case combination
The service returns the skippedDocumentTypes parameter only if the service skipped updating one or more publishable document types.
Key
Description
package
String Name of the package containing the skipped publishable document type.
name
String Fully qualified name of the skipped publishable document type.
reason
String Message indicating why the service did not update the publishable document type.
failedDocumentTypes
Document List Conditional. List of the publishable document types that the service could not update because of an error. The service returns the failedDocumentTypes parameter only if there were one or more publishable document types that the service could not update because of an error.
Key
Description
package
String Name of the package containing the publishable document type that the service could not update because of an error.
name
String Name of the publishable document type that the service could not update because of an error.
errors
String Text of the error message that prevented the service from updating the publishable document type.
providerSyncResults
Document List Conditional. Results of synchronizing the updated publishable document types with the messaging provider. The service only produces this output parameter when reportOnly is set to false and the service updated at least one publishable document type.
Key
Description
successfulPDTs
String List Fully qualified names of the publishable document types that the service synchronized successfully with the messaging provider.
unsuccessfulPDTs
String List Fully qualified names of the publishable document types that the service did not synchronize successfully with the messaging provider.
errors
Document List List of any errors that occurred during document type synchronization.
warnings
Document ListList of any warnings that occurred during document type synchronization.
Usage Notes
The pub.utils.messaging:syncDocTypesToUM service can be useful for updating the protocol buffer descriptors for multiple publishable document types at once. For example, if an Integration Server fix alters the way in which a protocol buffer descriptor is generated, to see the full effect of the fix, you would need to edit all of the publishable document types that use the protocol buffer encoding type, save them to cause an updated protocol buffer definition to be created and the updated protocol descriptor to be compiled, and then sync the publishable document types with the provider. While this can be done on an individual publishable document type basis with Designer, using the pub.utils.messaging:syncDocTypesToUM service enables the updating and synchronizing of many publishable document types at one time.
Thepub.utils.messaging.syncDocTypesToUM updates publishable document types contained in packages that begin with "Wm" when the document type is specified in documentTypeNames or the package is specified in packageNames only.
The pub.utils.messaging:syncDocTypesToUM service synchronizes the updated protocol buffer descriptor for a publishable document types with the corresponding Universal Messaging channel. Be sure to review the contents of providerSyncResults/errors and providerSyncResults/warnings for errors and warnings that Integration Servergenerated during synchronization.
If Integration Server did not successfully synchronize an updated publishable document type use the returned errors in providerSyncResults/errors to determine why Integration Server could not synchronize the publishable document type. Then, fix the cause of the error and synchronize the publishable document type with the messaging provider. You can synchronize documents using Designer or by executing the pub.publish:syncDocTypesToUM service.
The pub.utils.messaging:syncDocTypesToUM service will not modify any publishable document types that are locked for edit by another user or checked out at the time the service executes.
To use the pub.utils.messaging:sycnDocTypesToUM service to update a publishable document type, the user or client invoking the service must have Write access to the publishable document type.
To generate additional logging information in the Server log when the pub.utils.messaging:sycnDocTypesToUM service executes, set the logging level for the server log facility 0154 Protocol Buffer Encoding (Universal Messaging) to Debug or Trace.