← Creating Export Rule SetsImporting Redwood Server Objects with Imports →

Importing Objects

Most objects can be promoted to previously configured remote systems or exported as CAR files from within the user interface and later imported manually with imports, with the process definition System_Import_Archive or from the command line. To customize your imports, you can specify import rule sets. Import rule sets allow you to organize the flow of processes between Development, Test (Quality Assurance) and Production systems.

Import Rule Sets

Import rules define which objects get imported from CAR archives and the changes required by the new system, which allow one or more objects to be transported from one system into another seamlessly.

note

The Promotion Module requires the Module.ImportExport license key

Actions on import rule sets allow you to specify RedwoodScript code to be executed against the imported objects before they are written to the database. The code can be specified on the Actions tab and make use of the classes that you have stored in a library.

note

You should not persist the session in import rule set actions, as this is done for you at a later stage.

Promoting Objects from and to Remote Systems

You create a remote system of type Source or Both in the target system pointing at the source Redwood Server URL; the remote system would be pointing, for example, at your development system. Likewise you create a remote system of type Destination or Both in your source system pointing, for example, at your production system.

The source system needs to be able to access the target system on the port of the application server and needs valid credentials for a user that has sufficient privileges to import objects and create the objects to be imported.

note

It is recommended to edit objects in the development environment only and to test these changes in the test environment; several iterations are usually necessary. Once you are happy with the results, you promote the objects from test further into production. No object changes should be carried out in your Test environment; this way you keep your test environment clean of any changes that may later impact your production environment.

Importing Objects from CAR Files

A CAR file is located on a remote system, you would like to import it into Redwood Server. You have multiple choices, you can:

  • Run an import and use the file browser to upload the CAR file.
  • on-site-related topic Copy the file over to the target central Redwood Server or web server and submit System_Import_Archive, specifying the path/URL to the file, for example c:\\files\\Example.car or http://prd1.example.com/Example.car.
  • Copy the file over to a web server and submit System_Import_Archive, specifying the URL to the file, for example http://prd1.example.com/Example.car.
  • Execute the api-tool.jar with java (on the command line) and specify the path to the CAR file, requires a connection file created with jsecret -c.
  • Use curl (curl.exe on Windows) to PUT the file to https://<server>/<context>/api-rest/car or https://<region>.{runmyjobs,runmyfinance}.cloud/<company>/<environment>/api-rest/car, requires a basic Authorization header.
    • on-site-related topic https://<server>/<context>/api-rest/car - <server> is the FQDN of your server, <context>
    • cloud-related topic https://<region>.{runmyjobs,runmyfinance}.cloud/<company>/<environment>/api-rest/car - <region> region of your cloud instance, for example dublin, runmyfinance or runmyjobs, <company> your company, and <environment> the environment you want to use; you can see the correct value when you login to your environment with your browser.

Run an Import and Upload the CAR File with your Browser

  1. You navigate to Promotion > Imports and choose Submit from the context-menu.
  2. Choose browse and locate the CAR file, choose upload.
  3. Once the file is uploaded, choose Submit.

Copy the File to the Target Server or a Web Server and use System_Import_Archive

  1. Copy the file to the target server or web server, write down the path/URL.
  2. Navigate to "Definitions > Processes" and choose Submit from the context-menu of System_Import_Archive.
  3. Fill in the path or URL to the archive, choose Submit.

Importing CAR Files from the Command Line

Prerequisites

  • Java 1.8 or higher JVM
    • Unlimited strength Java Cryptography Extension (JCE) if your server uses TLS and/or SSL.
    • TLS options can be set using JVM specific system properties.
java -jar api-tool.jar import <connection_file> <CAR>  [-targetpartition <Partition>] [<ImportRuleSet>]

<connection_file> - file created using jsecret -c <connection_file> <server>
<CAR> - file to import
<Partition> - optional target partition for imported objects
<ImportRuleSet> - optional import rule set for imported objects

You use JVM parameters for any other options.

-targetpartition <partition> - where <partition> is a name of the partition; all objects in the CAR file will be created with this partition. Note that some objects, such as the library Custom and System_Defaults_System, must reside in the GLOBAL partition; the import will fail if you attempt to import objects that must be in the GLOBAL partition with the -targetpartition switch set to any other partition.

Examples

Using api-tool.jar:

jsecret -c ./example.conn https://dublin.runmyjobs.cloud/redwood-example/dev
username:
password:

java -jar api-tool.jar import ./example.conn example.car

java -jar api-tool.jar import ./example.conn c:\Promotion\Application_GL_Accounting.car -targetpartition FIN_EMEA FIN_EMEA.QA2Prod

java -jar api-tool.jar import ./example.conn c:\Promotion\Application_GL_Accounting.car -targetpartition FIN_EMEA

java -jar api-tool.jar import ./example.conn /tmp/Application_GL_Accounting.car FIN_EMEA.QA2Prodh

Using curl:

EncodedSecret="$(jecho -base64 "admin:admin")"
Authoriation="Authorization: Basic $EncodedSecret"
ContentType="Content-Type: application/octet-stream"

curl -H "$Authorization" -H $ContentType" -X PUT --data-binary "@example.car" https://s1.example.com/redwood/api-rest/car

Using jecho to encode the username and password for use in a header with curl to upload example.car to https://s1.example.com/redwood/api-rest/car

Using curl:

$EncodedSecret = "$(jecho -base64 "admin:admin")"
$Authoriation = "Authorization: Basic $EncodedSecret"
$ContentType = "Content-Type: application/octet-stream"

curl.exe -H "$Authorization" -H "$ContentType" -X PUT --data-binary "@C:\example.car" https://s1.example.com/redwood/api-rest/car

Using PowerShell to generate the base64 encoded username and password for use with curl.exe to upload C:\example.car to https://s1.example.com/redwood/api-rest/car

EncodedSecret="$(echo -n "admin:admin" | base64)"
Authoriation="Authorization: Basic $EncodedSecret"
ContentType="Content-Type: application/octet-stream"

curl -H "$Authorization" -H $ContentType" -X PUT --data-binary "@example.car" https://s1.example.com/redwood/api-rest/car

Using jecho to generate the base64 encoded username and password for use with curl.exe to upload C:\example.car to https://s1.example.com/redwood/api-rest/car

If you need to edit the objects in a CAR file, you can decompress it. You decompress CAR files with jar and other zip-compatible programs and re-create them.

note

You must run the CAR file using a JVM that has the unlimited strength Java Cryptography Extension (JCE) installed if your server uses TLS.

Embedding ImportRuleSets into CAR Files

You can embed import rule sets in car files by exporting the import rule set and extracting it out of the car file. After you have set the Name to ImportRuleSet, the partition to GLOBAL, and the Library to GLOBAL.None the XML file can be copied into the target car file in the following path: META-INF/ImportRuleSet.xml

A properties file can also be embedded in the car file and will be used in combination with the import rule set, provided it is located in the car file under META-INF/ImportRuleSet-parameters.properties.

See Also

import rule set ImportRuleSet

← Creating Export Rule SetsImporting Redwood Server Objects with Imports →