Skip to main content


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

Importing rules and data by submitting a request to an active instance

Updated on May 11, 2022

Import archive files that contain an application, product, branch, or ruleset to one or multiple target systems by submitting a request to an active instance of Pega Platform from a web service.

Before you begin:
  • Your access group must have the SchemaImport privilege and the dynamic system setting database/AutoDBSchemaChanges must be true.
  • If your access group does not have the SchemaImport privilege or the dynamic system setting database/AutoDBSchemaChanges is false, the system does not apply the schema changes and the failure response indicates the reason for failure.

Use the REST service URL to configure one or multiple targets to receive an imported archive file.

  1. Check that the following resources are available to you:
    • A running Pega Platform instance
    • Permission to do database changes
    • The archive file that is accessible from the client system
  2. For IBM Db2 for z/OS, configure the import properties.

    If you are importing an application with schema changes and a separate DB-Admin-DB-Name and you are using IBM Db2 for z/OS, configure the import parameters before you import the application, or the import will fail. For more information about configuring the import parameters, see IBM Db2 for z/OS: Preparing to import an application with schema changes and a separate DB-Admin-DB-Name. For more information about your application, see your database administrator.

  3. Configure the common properties of the prpcServiceUtils.properties file.

    Property name Value Required for Pega Cloud clients?
    pega.rest.server.urlThe URL for the REST service, specified in the following format:

    http:// <hostname> : <port> / <context> /PRRestService/

    For example: http://myhost:8080/prweb/PRRestService
    Yes
    pega.rest.usernameThe operator name on the target system with access to REST services. Yes
    pega.rest.passwordThe password of the specified operator. Yes
    pega.rest.proxy.host

    The host name of the REST proxy server. Do not use localhost as the host name.

    Required only when using a proxy for a URL.
    pega.rest.proxy.port

    The port for the REST proxy server.

    Required only when using a proxy for a URL.
    pega.rest.proxy.username

    The operator name on the REST proxy server with import and export access.

    Required only when using a proxy for the URL
    pega.rest.proxy.password

    The password of the REST proxy operator.

    Required only when using a proxy for the URL
    pega.rest.proxy.domain

    The domain of the REST proxy server.

    Required only when using a proxy for the URL
    pega.rest.proxy.workstation

    The workstation ID for the REST proxy server.

    Required only when using a proxy for the URL
    pega.rest.response.typeThe REST response type, either xml or json. The default value is json. Rollback, restore point, and update access group operations support only json. Not required
    user.temp.dir

    Enter the full path to the temporary directory. Leave this blank to use the default temporary directory. For more information about temporary directories, see Temporary files and temporary files directories .

    Not required

  4. Configure the import properties.

    Property name Value
    import.archive.pathWhen importing from a file system, the relative path to the archive from the \utils\ folder or the full path to the archive. If the path is a folder, the tool processes all archive files in that folder.
    import.modeThe import mode:
    • import: (Default) Update existing instances and remove duplicates. Use the import.existingInstances property to override this setting.
    • install: Import new instances. Do not import or update existing instances. The log file includes an exception message for each instance that already exists.
    • hotfix: Update existing instances and remove duplicates. If the archive time stamp is older than the existing instance, skip updating the instance or inserting the duplicate.
    import.existingInstancesHow the import action handles existing instances:
    • skip: (Default) Skip instances that already exist in different rulesets or versions.
    • override: Replace instances that already exist in different rulesets or versions.
    import.nofailonerrorSpecify whether to continue the import after a failure and skip instances that fail to import. The default is true. Set to false to stop the import if any import action fails.
    import.commitRateThe number of data instances processed with each database commit to balance memory usage and performance. The default of 100 is sufficient for most environments.
    import.compileLibrariesSpecify whether to compile libraries after import. The default is true.
    import.allowImportWithMissingDependenciesSpecify whether to allow the import to continue even if the archive is dependent on missing products. The default is false.
    import.preserveOrderSpecify whether to import archives in the order specified in the import file. The default is false, which does not enforce any order.
    import.codesetNameThe name of the code set to receive the Java .class files.
    import.codesetVersionThe code set version.
    import.async Specifies whether to run the process in asynchronous mode or synchronous mode. The default, true, is asynchronous, which returns a job ID that you can use later to check the job status. When this value is false, the process starts immediately and waits until completion. The choice of synchronous or asynchronous depends on the type of script you are writing.
    import.skipBackupIndicates whether to bypass creating a restore point during an import. It is a best practice to create restore points. To maintain best practices, keep import.skipBackup at the default setting, false.
    import.importFromRepositoryIndicates whether to import from a repository. The default is false, which imports from a file system. To import from a repository, set this to true.
    import.repositoryNameWhen importing from a repository, the name of the repository. The repository name is case sensitive.
    import.artifactTypeWhen importing from a repository, the artifact type you are importing. The supported types are application, product, branch, component, rulesetversion.
    import.archivePathWhen importing from a repository, the full path to the archive file. The archive path is case sensitive, for example: MyApp_01.01.01/ExportWizard/myFile.zip
    import.bypassSchemaSpecify whether to apply database schema changes during the import. The default is false. If you have already applied the schema changes manually, set this to true.
    import.insecureOperatorsAs a best practice, and by default, new operators are disabled on import and existing operators are not updated. Setting this to true does not disable new operators and allows updates of existing operators.
    import.allowInheritedConnectionsAllow importing inherited database name instances. The default setting is false.
    import.bypassColumnPopulationIf an import adds columns to existing tables, bypass automatically exposing and populating the new columns during the import. The default setting is false.
    import.bypassSchemaChangesToDescendantTablesIf an import changes an existing class, bypass automatically making changes to descendent tables. The default setting is false.

  5. Save and close the prpcServiceUtils.properties file.
  6. Run the prpcServiceUtils.bat script or the prpcServiceUtils.sh script with the import option, for example:
    prpcServiceUtils.bat import

    Pass one or more arguments.

    prpcServiceUtils script argument Value
    artifactsDirThe full path to the output file location, for those functions that generate output. The default is the /scripts/utils/logs directory.
    connPropFileThe full path to the serviceConnection.properties file that includes information for multiple targets.
    poolSizeThe thread pool size. The default is 5.
    requestTimeOutThe number of seconds the system waits for a response before failing with a time-out error. The default is 300 seconds.
    jobIdFileThe path to the job IDs file that is generated by the asynchronous operation.
    propFileThe property file name, to override the default prpcServiceUtils.properties file.
    operationNameSpecify the operation that generated the job ID for getStatus: import, export, expose, hotfix, or rollback.

  • Previous topic Importing rules and data from the command line
  • Next topic Importing rules and data by using a direct connection to the database

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.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us