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

You can 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.

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

To import an application, follow these steps:

  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
    pega.rest.server.url The URL for the REST service, specified in the following format:

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

    For example:

    http://myhost:8080/prweb/PRRestService

    Include the tenant hash only for multitenant systems.

    pega.rest.username The operator name on the target system with access to REST services.
    pega.rest.password The password of the specified operator.
    pega.rest.proxy.host Optional: The host name of the REST proxy server. Do not use localhost as the host name.
    pega.rest.proxy.port Optional: The port for the REST proxy server.
    pega.rest.proxy.username Optional: The operator name on the REST proxy server with import and export access.
    pega.rest.proxy.password Optional: The password of the REST proxy operator.
    pega.rest.proxy.domain Optional: The domain of the REST proxy server.
    pega.rest.proxy.workstation Optional: The workstation ID for the REST proxy server.
    pega.rest.response.type The REST response type, either xml or json. The default value is json. Rollback, restore point, and update access group operations support only json.
    user.temp.dir Optional: 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 .

  4. Configure the import properties:

    Property name Value
    import.archive.path When 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.mode The 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.existingInstances How 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.nofailonerror Specify 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.commitRate The 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.compileLibraries Specify whether to compile libraries after import. The default is true.
    import.allowImportWithMissingDependencies Specify whether to allow the import to continue even if the archive is dependent on missing products. The default is false.
    import.preserveOrder Specify whether to import archives in the order specified in the import file. The default is false, which does not enforce any order.
    import.codesetName The name of the code set to receive the Java .class files.
    import.codesetVersion The 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.skipBackup Indicates 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.importFromRepository Indicates 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.repositoryName When importing from a repository, the name of the repository. The repository name is case sensitive.
    import.artifactType When importing from a repository, the artifact type you are importing. The supported types are: application, product, branch, component, rulesetversion.
    import.archivePath When 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.bypassSchema Specify 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.insecureOperators As 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.allowInheritedConnections Allow importing inherited database name instances. The default setting is false.
    import.bypassColumnPopulation If an import adds columns to existing tables, bypass automatically exposing and populating the new columns during the import. The default setting is false.
    import.bypassSchemaChangesToDescendantTables If 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

    Optional: Pass one or more arguments.

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