Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Migrating document metadata

Updated on February 16, 2021

After all previous changes have been made, the requirements module is active and ready to use. It is now time to think about the migration strategy for the documents metadata.

During the time that the application has been running in 1G in your production environment, the system has collected multiple documents and metadata that have been stored in legacy data structures. The new version of the functionality comes with new data structures that provides flexibility and enables the future evolution of the module.

The migration process ensures that all documents and metadata captured in 1G becomes available for its use in 2G. There are two upgrade strategies supported:

On demand
Under this model, the metadata associated to the documents is steadily migrated as required by the system. Every time that one journey requires access to the documents of a given customer, the system executes an on-demand migration that copies all the document metadata available for that customer in the legacy data structures into the new ones. The process is transparent to final users, who does not know about the migration happening behind the scenes. This is the migration strategy by default.
Bulk migration
The application provides a set of tools to do a bulk migration of document metadata. The tools should be executed right after the activation of the 2G functionality in the production environment. Once it is executed, all the document metadata will remain in the new 2G data structures and the legacy data structures will not be accessed any more.

In order to determine which migration strategy is the more appropriate for your organization, the following factors should be considered:

Number of documents per customer
The on-demand migration can easily manage a handful of documents per customer without having a significant impact on the overall performance of the application. Organizations with a large number of documents per customer (in the order of dozens) may observe some delays at the time of performing certain operations (mainly, in the transition between data-capture and enrich, where the majority of the requirement cases are created).
Custom processes using 1G data structures
The on-demand strategy creates a situation where some of the data is in 1G data structures and some of it in 2G. All out-of-the-box processes have been prepared to manage this dual source of document metadata. However, if your organization has any custom process of this nature, it will need to be adapted to deal with the new data arrangement - this would include not only Pega processes but also external processes that might receive the data through different data export mechanism (for example, BIX).

On-demand migration


The main objective of the on-demand migration process is to migrate document metadata from its current storage in Data-WorkAttach-File class (pc_data_workattach database table) into the following two tables:

New database table to host document metadata. For more information, see Document metadata table in chapter Document and requirements metadata.
New table that records those customers that have already had their document metadata migrated. It avoids double executions of the migration on customers that have been already migrated.

The logic of the migration is executed every time the documents of a customer is requested through one the following two data pages:

  • D_RNGFetchMetadataDocumentsForCustomer
  • D_RNGDisplayExistingDocumentsForCustomer

In the current version of the application, these are the three invocation points:

Customer 360
While rendering the Documents tab in the Customer 360 view.
Synchronization engine
During the assessment of documents for reuse during requirements case creation.
Manual selection of documents
When the customer is uploading documents in the Satisfy stage, where they can select from the list of existing documents for that party.

Once the migration has been completed for a customer, it is not executed never again. That it is to say, for a given customer, the migration will only be triggered from one of the three invocation points listed above – the first one reached by the user or the system.


This migration strategy is set by default with the installation of Pega Client Lifecycle Management for Financial Services 8.5. Ensure the following dynamic system setting has the expected value:

PegaCLMFS Requirements/LegacyDocUpgradeStrategyOnDemand

Configuring document type automatic mapping

During the migration process, the system can automatically map document types used in 1G requirements into the new ones created for 2G. For example, if in 1G you were using a document type specific for a jurisdiction (for example, Passport Australia) and you want now to unify them under a single type (for example, Passport), you can configure the system to do it.

The data page D_LegacyToRNGDocsMappingData keeps the mapping rules available to the migration process. It is sourced through a report definition that reads from the table PegaReq-Data-Document-Mapping. Add entries to that table as required by your organization.

Extending the functionality

The following rules can be used to change the default behaviour of the application.

Rule nameRule typeUsage
RNGSetDocStatusForLegacyDocs_ExtData transformBy default, the on-demand migration sets the status of all documents to Uploaded-Collected. Modify this rule to set a different status.
RNGSetReuseFlagForLegacyDocs_ExtData transformBy default, the migration sets the reuse flag of the document (the one that determines which documents can be automatically reused) from the definition of the document type. Modify this rule to set a different value.
RNGConstructAssociateInfoData transformThe retrieval of documents associated to a customer was done in 1G using the AssociateInfo property. If for any reason you made changes that the content of that property, changes to this rule might be required.
RNGLoadLegacyDocs_ExtData transformCan be used to add logic to the migration of documents from 1G to 2G.

Bulk migration

The bulk migration is an accelerated version of the on-demand. It executes a logic equivalent to the on-demand migration but in a bulk manner. For a complete view of the process and how to execute it, see Bulk Migration of Document Metadata guide on Pega Client Lifecycle Management for Financial Services product page.

After the migration process has been executed, ensure that the following dynamic setting has the expected value – that will prevent that the system looks anymore to the legacy data structures:

PegaCLMFS Requirements/LegacyDocUpgradeStrategyBulk

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us