Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: In Configure migration – cards, updates in heading “Encrypted fields when showing in SmartACT" and added heading "Encrypted fields saved in PRIME".

This article describes how to migrate from SmartACT to Nexus PRIME.

Expandall

Prerequisites

Expand
titlePrerequisites

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 (for example, BIM_PCM) in the latest version are available

Step-by-step instruction

Preparation

Expand
titleSet up migration distribution and system requirements
  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.


Expand
titleSet database connection
  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 PRIME. The properties inside database.properties match those, described in PRIME installation.

    Code Block
    titleSmartACT 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
    titlePRIME 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
titleRun data encryption in SmartACT
  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:

    Code Block
    titleencryption-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
titlemigrate_general.properties


AtributeValueImportance

abortOnError

true/false

  • If true, the migration aborts (this is the default value).
  • If false, the migration continues despite errors.
printReporttrue/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.
printDetailReporttrue/false
  • If false, the migration does not write any details regarding the deviation of run data between SmartACT and PRIME (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
titlePerson status

These are examples of person statuses:

Code Block
titleExample: 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
titleExample: Person status in PRIME
...
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 (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
titleAssignment of master data template IDs to master data types in PRIME


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 (prime.person.coretemplate.names) are the same.



Expand
titleRole assignment

Every person from SmartACT is assigned the role BaseRoleSelfServiceUser as part of the migration to PRIME, 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>,...
prime.person.roles.deleted=<RollenNamePRIME>,...
...


Note

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



Expand
titleMap persons

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

The mapping of the persons is preset as follows:

SmartACT fieldPRIME fieldComment

COMPANY

Company
DEPARTMENTDepartment
EMAILEmail
FIRSTNAMEFirstName
INFOBIGTEXT0UPN
LASTNAMELastName
MD_CREATEDATECreationDate
MD_DATEModificationDate

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
titleUniqueness criterion of the person

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

Anchor
typeconversionperson
typeconversionperson

Expand
titleType conversion for the person


Field

Conversion ruleMapping 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
titleEncrypted 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 PRIME.



Expand
titleEncrypted fields saved in PRIME


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 (subsequently encrypt).



Expand
titleCard status in SmartACT


Code Block
titleExample:
...
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
titleCard status in PRIME


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 (attribute prime.card.states) are the same.



Expand
titleDefinitione of card template IDs in SmartACT


Code Block
titleExample:
...

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
titleAllocate card IDs to card types in PRIME


Code Block
...

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

...



Expand
titleMap cards

Mapping of card fields between PRIME 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 PRIME, 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 package.

The mapping of the cards is preset as follows:

SmartACT fieldPRIME fieldComment
CARD_NUMBER_TEXTCardNumber

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_DATEModificationDate
CRD_IDMigrationIdAlias and internal ID of the card.
CRD_MDID
Alias and internal ID that references the person's Data Pool field MigrationId.
CRD_PERSDATECreationDate

CRD_PERSFLAGS



CRD_REQID

CRD_STATEMeta_CoreObjectState_PcmDpEmployeeCard

Status of the card in SmartACT:
103: issued
104: active
105: temporarily locked
106: finally locked

CRD_TIMESTAMP



DEPARTMENTDepartment
EMAILEmail
FIRSTNAMEFirstName
INFOBIGTEXT0

UPN

LASTNAMELastName



Expand
titleUniqueness criterion of the card

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


Expand
titleMap card status between SmartACT and PRIME


Status SmartACTValue SmartACTMapping in PRIME
Card is personalized100None/not accepted
Card has been personalized101None/not accepted
Card has been personalized and confirmed102None/not accepted
Card was issued103Issued
Card is active104Active
Card is temporarily inactive105Inactive
Card is permanently blocked106Locked
Card was destroyed107None/not accepted
Repetition of personalization108None/not accepted
Card is reusable (for example, unallocated quota card)109None/not accepted

Card is on a transportation or shipping route

110None/not accepted
Card was destroyed during personalization 111None/not accepted

Card is temporarily inactive - by user group 1

113None/not accepted
Card is temporarily inactive - by user group 2114None/not accepted

Card is back again from a transportation or shipping route

115None/not accepted

Card is lost on a transportation or shipping route

116None/not accepted



Expand
titleType conversion for the card


FieldConversion ruleUsed mapping
TenantIdBIGDECIMAL_TO_STRING
MasterdataIdBIGDECIMAL_TO_STRING
MigrationIdBIGDECIMAL_TO_STRING
Meta_CoreObjectStateNUMBER_TO_STRING_CONDITIONAL

103 > "issued"
104 > "active"
105 > "inactive"
106 > "locked"



Expand
titleRelationship between card and person

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

AttributeValue

sourceDataPool

PcmDpEmployeeCard
sourceForeignKeyMasterdataId

targetDataPool

BaseDpEmployee
targetForeignKeyMigrationId


Configure migration - certificates

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

Expand
titleSmartACT 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
titlePRIME 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
titlePRIME 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 (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
titleMap certificates

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

CERT_ID

MigrationIdInternal ID of the certificate in SmartACT
CERT_DATEcreationDateCreation date

CERT_CARDID

CardId

Internal ID of referencing card

CERT_CAIDNone

Internal ID of the issuing CA (is configured in PRIME)

CERT_REFERENCENone

Internal ID of the predecessor certificate, which was "replaced" by the restore

CERT_CERTTEMPLATEIDcertTemplateIdInternal ID of certificate template in SmartACT
CERT_CERTSERIALcertSerialCertificate serial number
CERT_CARDSERIALNone
CERT_STATEMeta_CoreObjectState

Certificate status:
2: Certificate is locked
3: Certificate is valid
4: Certificate is invalid / never issued (for example, faulty request)

CERT_VALID_FROMvalidFromValidity start date
CERT_VALID_TOvalidToValidity end date
CERT_KEYARCHIVALNone

Note if this certificate has been restored:

0: no recovery
1: certificate has been restored

CERT_DATA

data

Certificate in binary format
CERT_RENEWAL_APPLIEDrenewalApplied

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
titleUniqueness criterion of the certificate

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


Expand
titleMap certificate status between SmartACT and PRIME


Status in SmartACTValue in SmartACTMapping in PRIME

Certificate is locked

2locked

Certificate is valid

3active

Certificate invalid / never issued (for example, incorrect request)

4none / will not be accepted



Expand
titleRelationship between certificate and card

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

AttributeValue

sourceDataPool

PcmDpCertificate
sourceForeignKeyCardId
targetDataPoolPcmDpEmployeeCard
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
titleLog 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
titlelog4j.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
titleMigrate 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 the table Tenant.


Expand
titleGeneral functions of migration, type conversion

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

AttributeDefinitionExample
fieldNameField name in PRIME

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

AttributeDefnition

sourceDataPool

Source data pool from which a relation to the target data pool shall be established.

sourceForeignKeySource 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



Related information