Using the Substitution Properties File

About the Substitution Properties File

If you specify –subprop in a batch export command, then the export tool creates an external substitution properties file. In this file, you can modify values that are associated with the exported objects so that the objects will function properly in the target system. For example, you can establish associations with objects and entities on the target system by specifying appropriate server names, source code repository paths, database schemas, archive paths, and other values. In addition, you can specify a different location in the SAS Folders tree for a particular object or objects.

The substitution properties file has the same path and filename that you specify in –package, except that it has the filename extension .subprop instead of .spk. For example, if the package file is named Package_1.spk, then the substitution properties file is named Package_1.subprop.

Note: Packages that are created in SAS 9.1.3 do not contain substitution properties files. For more information, see Using the Batch Import Tool to Import a Package That Was Created in SAS 9.1.3.

Use the Substitution Properties File to Update Metadata Associations

Before you import a package, you must open the substitution properties file in a text editor and make any necessary updates to associations with objects and entities on the target system.

For example, when you import a library, you must establish an association between the library and a SAS Application Server on the target system; and when you import a stored process, you must associate the stored process with a directory path for the associated source code on the target system. These are just examples of the many types of associations that might be necessary.

Follow these guidelines when updating the substitution properties file:

In the Connections: sections of the file (for example, Connections: Application Server), do not modify properties that have the word Source in the suffix. For example, do not modify ApplicationServer[1].SourceName=. Instead, modify the corresponding target property (for example, ApplicationServer[1].TargetName=).
You can modify any of the other properties as needed, unless the comments in the file indicate that the properties are not to be modified.
When updating properties, use the exact names of the resources as they appear on the target system. The names are case sensitive.

Here are examples of properties before the substitution properties file was modified:

[Connections: Application Server]
ApplicationServer[1].SourceName=SASAppTest
ApplicationServer[1].TargetName=SASAppTest

[Connections: Source Code Repository]
SourceCodeRepository[1].ApplicationServer=ApplicationServer[1]
SourceCodeRepository[1].SourceDirectory=c:\\StoredProcessesTest
SourceCodeRepository[1].TargetDirectory=c:\\StoredProcessesTest
SourceCodeRepository[1].CreateIfNeeded=false

Here are examples of modified properties in a substitution properties file. Note that only the target values have been modified. In addition, note that CreateIfNeeded has been changed to true. This means that the metadata definition for the source code repository will be created if it does not exist on the target system. (The physical location for the source code must already exist.)

Connections: Application Server]
ApplicationServer[1].SourceName=SASAppTest
ApplicationServer[1].TargetName=SASApp

[Connections: Source Code Repository]
SourceCodeRepository[1].ApplicationServer=ApplicationServer[1]
SourceCodeRepository[1].SourceDirectory=c:\\StoredProcessesTest
SourceCodeRepository[1].TargetDirectory=c:\\StoredProcesses
SourceCodeRepository[1].CreateIfNeeded=true

Use the Substitution Properties File to Specify New Folder Locations for Objects

In SAS 9.3, the batch import tool enables you to reorganize content as part of the promotion process. You can do so by specifying new folder locations for individual objects that you are importing, as follows:

Determine whether the substitution properties file contains a section for the object that you want to move. For example, the following section title applies to the Orion Star library that is located in Shared Data/Orion Star Data:
```
[/Shared Data/Orion Star Data/Orion Star(Library)]
```
If you do not find a section title for the object that you want to move, then add a section title to the file using the following syntax. Be sure to include the entire path, relative to SASFolders. (You can obtain the path information from the export log, if necessary.)
```
[path-relative-to-SASFolders/object-name(object-type)]
```
Immediately following the object’s section title, add an entry that specifies the folder to which you want to move the object. The specified folder must already exist on the target metadata server. Be sure to include the entire path, relative to SASFolders. Use the following syntax:
```
Framework.FolderPath=path-relative-to-SASFolders(Folder)
```

Add these entries for each object or folder that you want to move. For example:

Suppose /Shared Data/Orion Star Data on the source metadata server contains three tables (CUSTOMER_DIM, ORDER_FACT, and PRODUCT_DIM) and two information maps (Customer Orders and Product Sales). To move these objects to an already-existing folder called /Shared Data/Imported Data on the target metadata server, you would update the substitution properties file with the following entries:
```
[/Shared Data/Orion Star Data/CUSTOMER_DIM(Table)]
Framework.FolderPath=/Shared Data/Imported Data(Folder)

[/Shared Data/Orion Star Data/ORDER_FACT(Table)]
Framework.FolderPath=/Shared Data/Imported Data(Folder)

[/Shared Data/Orion Star Data/PRODUCT_DIM(Table)]
Framework.FolderPath=/Shared Data/Imported Data(Folder)

[/Shared Data/Orion Star Data/Customer Orders(InformationMap)]
Framework.FolderPath=/Shared Data/Imported Data(Folder)

[/Shared Data/Orion Star Data/Product Sales(InformationMap)]
Framework.FolderPath=/Shared Data/Imported Data(Folder)
```
On the target system, the three tables will appear directly under the Imported Data folder.
If you want to move the entire /Shared Data/Orion Star Data folder and its contents to an already-existing folder called /Shared Data/Imported Data on the target metadata server, you would update the substitution properties file with the following entries:
```
[/Shared Data/Orion Star Data(Folder)]
Framework.FolderPath=/Shared Data/Imported Data(Folder)
```
The imported objects will appear in the path /Shared Data/Imported Data/Orion Star Data on the target system.

Note: If you used the –includeDep option to export an object’s dependent objects, the dependent objects are not moved automatically. You must move the dependent objects separately.

Apply the Substitution Properties File

To apply the changes that you made to the substitution properties file, specify the –subprop option when you run the batch import tool.