Migrate from SmartACT to Identity Manager

This is a summary of what must be in place before the migration starts. More information is found in the article.

• Java 8 Runtime is installed
• JRE_HOME is set as environmental variable
• java-security-policy-fix is recorded
• Databases are correctly registered in database.properties
• Run Data Encryption Certificate is provided and configured in encryption-config.xml
• Personalization is done correctly in migrate_persons.properties
• Configuration for cards/tokens is correct in migrate_cards.properties
• Certificates configuration is correct in migrate_certificates.properties (PKI only Card management)
• Smart ID configurations (for example, Base, Physical ID, DIgital ID) in the latest version are available

1. Install the current version of Java Runtime Environment (JRE).
2. Set JRE_HOME to the installation directory of java jre
   (for example: C:\Program Files\Java\jre1.8.0_161\bin)
3. Import the java-security-policy-fix for the installed Java version. The jce-policy-8.zip is provided with the migration package.
4. Unpack the migration package of delivery in a directory of your choice.

1. Go to the specified migration directory.

2. In the file database.properties specify the attributes HOST_NAME, DB_PORT, DB_NAME, USER_NAME and USER_PASSWORD for SmartACT and Identity Manager. The properties inside database.properties match those, described in PRIME installation.

   SmartACT database

   CODE

   ### SmartACT Database
   smartAct.jdbcUrl=jdbc:sqlserver://<HOST_NAME>:<DB_PORT>;databaseName=<DB_NAME>;AUTO_SERVER=TRUE
   #smartAct.jdbcUrl=jdbc:sqlserver://<HOST_NAME>:<DB_PORT>;databaseName=<DB_NAME>;instance=<INSTANCE_NAME>;AUTO_SERVER=TRUE - verwendet für SQLEXPRESS Datenbank-Server
   smartAct.user=<USER_NAME>
   smartAct.password=<USER_PASSWORD>

   Identity Manager database

   CODE

   ### PRIME Database
   prime.jdbcUrl=jdbc:sqlserver://<HOST_NAME>:<DB_PORT>;databaseName=<DB_NAME>;AUTO_SERVER=TRUE
   #prime.jdbcUrl=jdbc:sqlserver://<HOST_NAME>:<DB_PORT>;instance=<INSTANCE_NAME>;databaseName=<DB_NAME>;AUTO_SERVER=TRUE - verwendet für SQLEXPRESS Datenbank-Server
   prime.user=<USER_NAME>
   prime.password=<USER_PASSWORD>
   ...

You must have read/write rights of the SQL users on the databases.

1. Make sure that the certificate for encrypting run data in SmartACT (idexpertcert02.p12) is stored in the directory config. The migration tools contains this certificate, if it is not supplied by you.

2. Open the file encryption-config.xml and check if the value of the attribute pin under the key idexpertcert02 is correct, otherwise set the value:

   encryption-config.xml

   CODE

   ...
   	<keys>
   		<key name="idexpertcert02">
   			<type name="pkcs12" locationValue="config/idexpertcert02.p12" 
   pin="XXXX"/>
   		</key>
   	</keys>
   ...

These are examples of person statuses:

...
smartact.person.state.active=1
smartact.person.state.inactive=2
smartact.person.states=${smartact.person.state.active}, 
${smartact.person.state.inactive}

...
prime.person.state.active=active
prime.person.state.inactive=inactive
prime.person.states=${prime.person.state.active}, ${prime.person.state.inactive}
...

Make sure that the number of states between SmartACT (attribute smartact.person.states) and Identity Manager (attribute prime.person.states) are always the same.

For the attribute smartact.masterdata.template.ids, enter one or more comma-separated Master data template IDs if you only want to migrate specific master data templates.

Every person from SmartACT is assigned the role BaseRoleSelfServiceUser as part of the migration to Identity Manager, so access via USSP is possible. This can be customized in migrate_persons.properties under the parameter prime.person.roles.added.

...
prime.person.roles.added=BaseRoleSelfServiceUser,<RoleNameIdM>,...
prime.person.roles.deleted=<RoleNameIdM>,...
...

The roles are specified as a comma-separated list. These are applied to all person objects during the migration process.

The mapping of the data fields between Identity Manager and SmartACT is configured in the file spring\migrate-persons-batch_jobs-beans.xml. The assignment must be adjusted according to the use of the data fields in the following area:

	<util:map id="personFieldMapping">
		<!-- <entry key="SmartAct_ColumnName" 
value="Prime_CoreTemplate_FieldName"/> -->

		<!-- migration specific mapping -->
		<entry key="MigrationId" value="MigrationId"/>
		<entry key="MD_MDTID" value="Meta_CoreTemplateName"/>
....
	</util:map>

In Identity Manager, new data pool fields might have to be created as additional fields. At least, MigrationId should be added as a numeric field, as this is not part of the standard Identity Manager modules.

The mapping of the persons is preset as follows:

For this, the MigrationId field is used, which is already used in SmartACT as uniqueness criterion.

Mapping of card fields between Identity Manager and SmartACT is configured in the spring\migrate-cards-batch_jobs-beans.xml file.

The assignment must be adjusted according to the use of the data fields in the following area:

<util:map id="cardFieldMapping">
		<!-- <entry key="SmartAct_ColumnName" 
value="Prime_CoreTemplate_FieldName"/> -->

		<!-- migration specific mapping -->
		<entry key="MigrationId" value="MigrationId"/>
....
	</util:map>

In Identity Manager, new data pool fields have to be created as additional fields. At least the MigrationId should be added as a numeric field, as this is not part of the standard Identity Manager modules.

The mapping of the cards is preset as follows:

The field MigrationId is used, which is already used in SmartACT as uniqueness criterion.

The following relation is defined especially for the card (see also Relation between the objects)

...
prime.certificate.state.locked = locked
prime.certificate.state.active = active
prime.certificate.states = ${prime.certificate.state.locked}, $ {prime.certificate.state.active}
...

Make sure that the number of states between SmartACT (attribute smartact.certificate.states ) and Identity Manager (attribute prime.certificate.states) are the same.

If a card is permanently replaced in SmartACT, the new certificate entry points to the preceding certificate. When migrating certificates, only the "origin certificates" are adopted. This is easy to determine by keeping track of the certificate reference until you find a certificate without predecessor.

The mapping of card data fields between Identity Manager and SmartACT is configured in the file spring\migrate-certificates-batch_jobs-beans.xml. The assignment must be adjusted according to the use of the data fields in the following area:

<util:map id="certificateFieldMapping">
		<!-- <entry key="SmartAct_ColumnName" 
value="Prime_CoreTemplate_FieldName"/> -->


		<!-- migration specific mapping -->
		<entry key="MigrationId" value="MigrationId"/>
....
	</util:map>

In Identity Manager, new data pool fields have to be created as additional fields. At least, MigrationId should be added as a numeric field, as this is not part of the standard Identity Manager modules.

The mapping of the certificates is preset as follows:

The field MigrationId is used, which is already used in SmartACT as uniqueness criterion.

Specifically for the certificate, the following relation is defined (see also Relation between the objects)

During the migration, log files are created in the subdirectory logs/ 

• batch.log
  Contains the complete logging of the data migration, except the migration of old CA certificates to Nexus Certificate Manager.
• batch_skipped.log
  Contains a log of all data records (with all data) that could not be transferred, including the error message. This is for error analysis.
• batch_overview.log
  Is only created when the data migration completes successfully. Contains a quantitative comparison of the two databases after migration, structured by tenant, type and status.

The files are created on every new run and they will overwrite existing ones. For a fully documented step-by-step documentation of the data records, these must be saved by the user before the next run is performed.

If necessary, you can customize the path of the log messages by opening the log4j.xml file and specifying the file (Attribute File) and maximum index (attribute MaxBackupIndex) in the sections BATCHLOG, BATCHLOG_SKIPPED and BATCHLOG_OVERVIEWLOG as below. The log levels should only be adjusted after consultation with the consultant or project manager at Nexus, as these can have a major impact on the duration of the migration.

...
<!-- definition of output sources -->

	<!-- Logging to Console -->
	<appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
		<param name="Encoding" value="UTF-8"/>
		<layout class="org.apache.log4j.PatternLayout">
			<param name="ConversionPattern" value="%d %-5p %-25t (%F:%L) : %m%n"/>
		</layout>
	</appender>
	<appender name="BATCHLOG" class="org.apache.log4j.RollingFileAppender">
		<param name="File" value="logs/batch.log" />
		<param name="Append" value="true" />
		<param name="Encoding" value="UTF-8"/>
		<param name="BufferedIO" value="false" />
		<param name="MaxBackupIndex" value="40" />
		<param name="MaxFileSize" value="50MB" />
		<layout class="org.apache.log4j.PatternLayout">
			<param name="ConversionPattern" value="(%d) %-5p %-15t (%F:%L) : %m%n"/>
		</layout>
	</appender>


	<appender name="BATCHLOG_SKIPPED" class="org.apache.log4j.RollingFileAppender">
		<param name="File" value="logs/batch_skipped.log" />
		<param name="Append" value="true" />
		<param name="Encoding" value="UTF-8"/>
		<param name="BufferedIO" value="false" />
		<param name="MaxBackupIndex" value="40" />
		<param name="MaxFileSize" value="50MB" />
		<layout class="org.apache.log4j.PatternLayout">
			<param name="ConversionPattern" value="(%d) %-5p %-15t (%F:%L) : %m%n"/>
		</layout>
	</appender>
	
	<appender name="BATCHLOG_OVERVIEWLOG" class="org.apache.log4j.RollingFileAppender">
		<param name="File" value="logs/batchoverview.log" />
		<param name="Append" value="true" />
		<param name="Encoding" value="UTF-8"/>
		<param name="BufferedIO" value="false" />
		<param name="MaxBackupIndex" value="40" />
		<param name="MaxFileSize" value="2MB" />
		<layout class="org.apache.log4j.PatternLayout">
			<param name="ConversionPattern" value="(%d): %m%n"/>
		</layout>
	</appender>

	<appender name="BATCHLOG_CERTIFICATEEXPORT" class="org.apache.log4j.RollingFileAppender">
		<param name="File" value="logs/batch_certCA.log" />
		<param name="Append" value="true" />
		<param name="Encoding" value="UTF-8"/>
		<param name="BufferedIO" value="false" />
		<param name="MaxBackupIndex" value="40" />
		<param name="MaxFileSize" value="2MB" />
		<layout class="org.apache.log4j.PatternLayout">
			<param name="ConversionPattern" value="(%d): %m%n"/>
		</layout>
	</appender>
...

The term client refers to the master data template from SmartACT (table T_MASTERDATATEMPLATE), which is used as the data source of the migration. All tenants are created with their own IDs, the initially existing tenant with ID 1 remains. The clients are stored in Identity Manager in the table Tenant.

When mapping the person, type conversion rules can be specified for the fields in Identity Manager (see Type conversion for the person). A conversion rule is defined as follows:

When saving, the corresponding record (object) can be linked to one or more objects, for example:

• Card with person
• Certificate with card and person

The desired relations are set using the attribute dataPoolRelations, which refers to a list consisting of one or more relations of type DataPoolRelation. Person should be related to card and card should be related to certificate.

DataPoolRelation is defined as follows: