This article describes how to migrate from SmartACT to Smart ID Identity Manager (PRIME).

Prerequisites

Expand

title	Prerequisites

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)
PRIME modules Smart ID configurations (for example, BIM_PCM, Base, Physical ID, DIgital ID) in the latest version are available

Step-by-step instruction

Preparation

Expand

title	Set up migration distribution and system requirements

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

Expand

title	Set database connection

Go to the specified migration directory.

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

Code Block

title	SmartACT database

### 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>

Code Block

title	PRIME Identity Manager database

### 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>
...

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

Expand

title	Run data encryption in SmartACT

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.
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:
Code Block
title encryption-config.xml
... <keys> <key name="idexpertcert02"> <type name="pkcs12" locationValue="config/idexpertcert02.p12" pin="XXXX"/> </key> </keys> ...

Configure migration - general

The configuration is done in the migrate_general.properties file, which is structured as follows.

Expand

title	migrate_general.properties

Atribute	Value	Importance
abortOnError	true/false	If true, the migration aborts (this is the default value). If false, the migration continues despite errors.
printReport	true/false	If true, the migration saves a migration summary of the migrated tenants and their run data (this is the default value). If false, there is no migration overview.
printDetailReport	true/false	If false, the migration does not write any details regarding the deviation of run data between SmartACT and PRIME Identity Manager (this is the default value). If true, the migration writes details about the deviation of run data (status and number) in the migration overview.
prime.username		Name of the administrator of the respective tenant.
prime.userpassword		The administrator's password.
prime.tenantId		Tenant ID

Configure migration - persons

The configuration is done in the migrate_persons.properties file, which is structured as follows.

Expand

title	Person status

These are examples of person statuses:

Code Block

title	Example: Person status in SmartACT

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

Code Block

title	Example: Person status in PRIMEIdentity Manager

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

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

Note
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.

Expand

title	Assignment of master data template IDs to master data types in PRIMEIdentity Manager

Code Block
... prime.person.coretemplate.names=BaseCtEmployee ...

Note
Make sure that the number of master data types between SmartACT (`smartact.masterdata.template.ids`) and PRIME and Identity Manager (`prime.person.coretemplate.names`) are the same.

Expand

title	Role assignment

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

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

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

Expand

title	Map persons

The mapping of the data fields between PRIME 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:

Code Block

	<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>

Note
In PRIMEIdentity 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 PRIME packagestandard Identity Manager modules.

The mapping of the persons is preset as follows:

SmartACT fieldPRIME field	Identity Manager field	Comment
COMPANY	Company
DEPARTMENT	Department
EMAIL	Email
FIRSTNAME	FirstName
INFOBIGTEXT0	UPN
LASTNAME	LastName
MD_CREATEDATE	CreationDate
MD_DATE	ModificationDate
MD_ID	MigrationId	Alias and internal ID of the Master record in SmartACT
MD_MDTID	TenantId Meta_CoreTemplateName_ BaseDpEmployee is set via `master data type_location`	Alias and internal ID of the MDT in SmartACT
MD_REASON	Meta_CoreObjectStateChangeReason_BaseDpEmployee
MD_STATE	Meta_CoreObjectState_ BaseDpEmployee	Status of the person in SmartACT (refer to Type conversion for the person) 1: Active 2: Inactive 3: Deleted

Expand

title	Uniqueness criterion of the person

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

Anchor

	typeconversionperson
	typeconversionperson

Expand

title	Type conversion for the person

Field	Conversion rule	Mapping used
MasterdataId	BIGDECIMAL_TO_LONG
Meta_CoreObjectState	NUMBER_TO_STRING_CONDITIONAL	1 > "registered" 2 > "active" 3 > "inactive"

Configure migration - cards

The configuration is done in the migrate_cards.properties file, which is structured as follows.

Expand

title	Encrypted fields when showing in SmartACT

Code Block

...
smartact.card.field.PIN=PIN
smartact.card.field.PUK=PUK
smartact.card.field.CARD_CRKEY=CARD_CRKEY
smartact.card.encrypted.fields=${smartact.card.field.PIN}, ${smartact.card.field.PUK}, ${smartact.card.field.CARD_CRKEY}
...

Note
All encrypted fields have to be available in this list otherwise the encrypted value which was created with SmartACT certificate will be saved in PRIMEIdentity Manager.

Expand

title	Encrypted fields saved in PRIMEIdentity Manager

Code Block

...
prime.card.field.PIN=PIN
prime.card.field.PUK=PUK
prime.card.field.CardManagerKey=CardManagerKey
prime.card.encrypted.fields=${prime.card.field.PIN}, ${prime.card.field.PUK}, ${prime.card.field.CardManagerKey}
...

Note
A field which was not encrypted in SmartACT/ProACT can be encrypted in PRIME in Identity Manager (subsequently encrypt).

Expand

title	Card status in SmartACT

Code Block

title	Example:

...
smartact.card.state.issued=103
smartact.card.state.active=104
smartact.card.state.inactive=105
smartact.card.state.locked=106
smartact.card.states=${smartact.card.state.active}, ${smartact.card.state.inactive}, ${smartact.card.state.locked},${smartact.card.state.issued}
...

Expand

title	Card status in PRIMEIdentity Manager

Code Block

...
prime.card.state.issued=issued
prime.card.state.active=active
prime.card.state.inactive=inactive
prime.card.state.locked=locked
prime.card.states=${prime.card.state.active}, ${prime.card.state.inactive}, 
${prime.card.state.locked},${prime.card.state.issued}

Note
Make sure that the number of status between SmartACT (attribute `smartact.card.states`) and PRIME and Identity Manager (attribute `prime.card.states`) are the same.

Expand

title	Definitione of card template IDs in SmartACT

Code Block

title	Example:

...

smartact.card.template.ids = 3320,3321,3322, ...

...

Note
Enter one or more card template IDs separated by commas. Enter all card types that you shall use.

Expand

title	Allocate card IDs to card types in PRIMEIdentity Manager

Code Block
... prime.card.coretemplate.names = MyCtEmployeeCard, MyCtAdminCard, MyCtEmployeeCard ...

Expand

title	Map cards

Mapping of card fields between PRIME 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:

Code Block

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

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

Note
In PRIMEIdentity 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 PRIME packageIdentity Manager modules.

The mapping of the cards is preset as follows:

SmartACT fieldPRIME field	Identity Manager field	Comment
CARD_NUMBER_TEXT	CardNumber
CARD_PIN	PIN
CARD_PUK	PUK
CARDOS_CHIP_ID	ICCSN
CRD_CTID	Meta_CoreTemplateName_PcmDpEmployeeCard	Internal ID of the master data template in SmartACT, which is linked to the core template name by further mapping (see `coreTemplateMap` or `cardCoreTemplateMap`)
CRD_DATE	ModificationDate
CRD_ID	MigrationId	Alias and internal ID of the card.
CRD_MDID		Alias and internal ID that references the person's Data Pool field `MigrationId`.
CRD_PERSDATE	CreationDate
CRD_PERSFLAGS
CRD_REQID
CRD_STATE	Meta_CoreObjectState_PcmDpEmployeeCard	Status of the card in SmartACT: 103: issued 104: active 105: temporarily locked 106: finally locked
CRD_TIMESTAMP
DEPARTMENT	Department
EMAIL	Email
FIRSTNAME	FirstName
INFOBIGTEXT0
UPN
LASTNAME	LastName

Expand

title	Uniqueness criterion of the card

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

Expand

title	Map card status between SmartACT and PRIMEIdentity Manager

Status SmartACT	Value SmartACT	Mapping in PRIMEin Identity Manager
Card is personalized	100	None/not accepted
Card has been personalized	101	None/not accepted
Card has been personalized and confirmed	102	None/not accepted
Card was issued	103	Issued
Card is active	104	Active
Card is temporarily inactive	105	Inactive
Card is permanently blocked	106	Locked
Card was destroyed	107	None/not accepted
Repetition of personalization	108	None/not accepted
Card is reusable (for example, unallocated quota card)	109	None/not accepted
Card is on a transportation or shipping route	110	None/not accepted
Card was destroyed during personalization	111	None/not accepted
Card is temporarily inactive - by user group 1	113	None/not accepted
Card is temporarily inactive - by user group 2	114	None/not accepted
Card is back again from a transportation or shipping route	115	None/not accepted
Card is lost on a transportation or shipping route	116	None/not accepted

Expand

title	Type conversion for the card

Field	Conversion rule	Used mapping
TenantId	BIGDECIMAL_TO_STRING
MasterdataId	BIGDECIMAL_TO_STRING
MigrationId	BIGDECIMAL_TO_STRING
Meta_CoreObjectState	NUMBER_TO_STRING_CONDITIONAL	103 > "issued" 104 > "active" 105 > "inactive" 106 > "locked"

Expand

title	Relationship between card and person

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

Attribute	Value
sourceDataPool	PcmDpEmployeeCard
sourceForeignKey	MasterdataId
targetDataPool	BaseDpEmployee
targetForeignKey	MigrationId

Configure migration - certificates

The configuration is done in the migrate_certificates.properties file, which is structured as follows.

Expand

title	SmartACT certificate status

Code Block
... smartact.certificate.state.locked = 2 smartact.certificate.state.active = 3 smartact.certificate.states = ${smartact.certificate.state.locked}, $ {smartact.certificate.state.active} ...

Expand

title	PRIME Identity Manager certificate template

Code Block
... prime.certificate.coretemplate.names = MyCtMigration%Certificate ...

Note
For the attribute `smartact.certificate.template.ids`, use one or more comma-separated Template IDs.

Expand

title	PRIME Identity Manager certificate status

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

Note
Make sure that the number of states between SmartACT (attribute `smartact.certificate.states` ) and PRIME 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.

Expand

title	Map certificates

The mapping of card data fields between PRIME 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:

Code Block

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


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

Note
In PRIMEIdentity 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 PRIME package.

The mapping of the certificates is preset as follows:

SmartACT fieldPRIME field	Identity Manager field	Comment
CERT_ID	MigrationId	Internal ID of the certificate in SmartACT
CERT_DATE	creationDate	Creation date
CERT_CARDID	CardId	Internal ID of referencing card
CERT_CAID	None	Internal ID of the issuing CA (is configured in PRIMEIdentity Manager)
CERT_REFERENCE	None	Internal ID of the predecessor certificate, which was "replaced" by the restore
CERT_CERTTEMPLATEID	certTemplateId	Internal ID of certificate template in SmartACT
CERT_CERTSERIAL	certSerial	Certificate serial number
CERT_CARDSERIAL	None
CERT_STATE	Meta_CoreObjectState	Certificate status: 2: Certificate is locked 3: Certificate is valid 4: Certificate is invalid / never issued (for example, faulty request)
CERT_VALID_FROM	validFrom	Validity start date
CERT_VALID_TO	validTo	Validity end date
CERT_KEYARCHIVAL	None	Note if this certificate has been restored: 0: no recovery 1: certificate has been restored
CERT_DATA	data	Certificate in binary format
CERT_RENEWAL_APPLIED	renewalApplied	Note whether a renewal of the certificate is pending in User Self Service: 0: no renewal 1: certificate must be renewed (no longer required after the user has completed the renewal process in the User Self Service)
CERT_KEYDATA
MDT_ID	tid issuer modificationDate creationUser modificationUser	Internal ID of the client Issuer Change date Create user Change user

Expand

title	Uniqueness criterion of the certificate

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

Expand

title	Map certificate status between SmartACT and PRIMEIdentity Manager

Status in SmartACT	Value in SmartACT	Mapping in PRIMEin Identity Manager
Certificate is locked	2	locked
Certificate is valid	3	active
Certificate invalid / never issued (for example, incorrect request)	4	none / will not be accepted

Expand

title	Relationship between certificate and card

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

Attribute	Value
sourceDataPool	PcmDpCertificate
sourceForeignKey	CardId
targetDataPool	PcmDpEmployeeCard
targetForeignKey	MigrationId

Start migration

To start the migration:

run the batch file start_migration.bat on Windows
or
run the shell script start_migration.sh on Linux/Unix.

Note
Under Unix/Linux, give the shell scripts the correct rights using `chmod`.

Expand

title	Log migration

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.

Note
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.

Code Block

title	log4j.xml

...
<!-- 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>
...

Expand

title	Migrate tenants

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 PRIME in Identity Manager in the table Tenant.

Expand

title	General functions of migration, type conversion

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

Attribute	Definition	Example
fieldName	Field name in PRIMEIdentity Manager	Meta_CoreObjectState, Meta_CoreObjectStateChangeReason, etc.
conversionType	The following conversion types are supported: NUMBER_TO_STRING NUMBER_TO_STRING_CONDITIONAL STRING_TO_NUMBER STRING_TO_NUMBER_CONDITIONAL DATE_TO_STRING STRING_TO_DATE BIGDECIMAL_TO_LONG	NUMBER_TO_STRING: 104 → "104" NUMBER_TO_STRING_CONDITIONAL: 104 → "active" STRING_TO_NUMBER: "104" → 104 STRING_TO_NUMBER_CONDITIONAL: "one" → "1", "two" → "2", ... DATE_TO_STRING: (refer to parsePattern) STRING_TO_DATE: (refer parsePattern) BIGDECIMAL_TO_LONG: SmartACT specific conversion of numerical values
selection	A choice for the conditional conversion	104 → "active" 105 → "inactive"
parsePattern	Formatting pattern for the conversion type DATE_TO_STRING or STRING_TO_DATE	yyyy-MM-dd HH: mm: ss.SSS

Anchor

	relationbetweenobjects
	relationbetweenobjects

Expand

title	Relation between the objects

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:

Attribute	Defnition
sourceDataPool	Source data pool from which a relation to the target data pool shall be established.
sourceForeignKey	Source data pool field that references a data pool field in the destination data pool.
targetDataPool	Target data pool from which to relate to the source data pool shall be established.
targetForeignKey	Target data pool field that references a data pool field in the source data pool

Versions Compared

Old Version 3

New Version 4

Key

Prerequisites

Step-by-step instruction

Preparation

Configure migration - general

Configure migration - persons

Configure migration - cards

Configure migration - certificates

Start migration

Related information

Page Comparison

Versions Compared

Old Version 3

New Version 4

Key

Prerequisites

Step-by-step instruction

Preparation

Configure migration - general

Configure migration - persons

Configure migration - cards

Configure migration - certificates

Start migration

Related information