Upgrade from PRIME 3.10 to PRIME 3.11

This article is valid from Nexus PRIME 3.11

This article describes the steps that must be done when upgrading Smart ID Identity Manager from version 3.10 to 3.11. The instructions cover relevant changes for standard features that can be used by configuration in PRIME Designer or configuration files. Customization changes in internal APIs etc are not included. These instructions apply when upgrading the 3.10 standard packages to 3.11.

If you upgrade from a more previous version, you must do the upgrades step by step, that is, first upgrade from 3.9 to 3.10 and then from 3.10 to 3.11. If that is the case, see also Upgrade from PRIME 3.9 to PRIME 3.10.

Prerequisites

Upgraded PRIME to 3.11, see Upgrade Identity Manager.

Step-by-step instructions

Adapt PRIME processes to new Execute Search service task

For PRIME 3.11, the new service task Execute Search has replaced beans in several processes in PRIME. Some beans in all custom beans files have been removed. For more information on Execute Search, see Process - Standard service tasks in Identity Manager.

To adapt to the new setup, the PRIME configuration must be modified. There are two options to do this:

Option 1 - Manually update processes

In your current configuration, update the PRIME processes that are listed below. Compare each process with the corresponding process for 3.11 and update it accordingly.

These processes must be updated

Smart ID Base module

BaseProcSaveEmployeeWithUniqueness					Save employee with unique email
BaseProcSaveVisitorWithUniqueEmail					Save visitor with unique email

*************************************************************************************

Smart ID Digital ID
									
PcmProcActivatePMProfile							Install certificates on mobile Id (was: Request PM certificates)
PcmProcContractorCardWithApproval                   Request contractor card
PcmProcContractorCardWithoutApproval                Create contractor card
PcmProcDeactivateContractor                         Deactivate contractor
PcmProcDeactivateEmployee                           Deactivate employee
PcmProcDeactivateEmployeeCard                       Deactivate employee card
PcmProcDeactivateVisitor                            Deactivate visitor
PcmProcEmployeeCardProduction                       Employee Card Production
PcmProcEmployeeCardWithApproval                     Request employee card
PcmProcEmployeeCardWithoutApproval                  Create employee card
PcmProcEmployeeTemporaryCard						Create employee temporary card	
PcmProcLockEmployeeCard								Lock employee card					
PcmProcLockEmployeeTempCard							Lock employee Temp Card
PcmProcLockPersonalMobile							Lock mobile Id
PcmProcLockPersonalX								Lock virtual smartcard
PcmProcProvisioningCertificateToVSC					Provisoning certificate to virtual smartcard
PcmProcReactivateEmployeeCard						Reactivate employee card 
PcmProcRenewEmployeeCard							Renew employee card
PcmProcRenewVirtualSmartcard					    Renew virtual smartcard
PcmProcRepeatEmployeeCardProduction					Repeat Employee Card Prod.
PcmProcReplaceEmployeeCard							Replace employee card
PcmProcReplaceVSC									Replace virtual smartcard
PcmProcUSSPEmployeeCardWithApproval					Request USSP-Employee card
PcmProcUSSPEmployeeCardWithoutApproval				Create USSP-Employee card
PcmProcWithdrawEmployeeTempCard						Withdraw Employee Temp Card
PcmSubProcCreationOfVSC								Creation of virtual smartcard
PcmSubProcMobileId									Subprocess Mobile Id
PcmSubProcReplaceEmployeeCard						Subprocess Replace employeecard

PstmProcProceedSoftwareTokenRequest					Proceed softtoken request		
PstmProcReplaceSofttokenUSSP						Replace softtoken
PstmProcRevokeAllSofttokenTypes						Revoke all softtoken types
PstmProcSendCertificatesToStand-In					Send encryption certificates to stand-in
PstmProcSubSubProcRenewSofttoken					Subprocess Renew softtoken												
PstmSubProcReplaceSofttokenUSSP						Subprocess Replace Softtoke USSP

*************************************************************************************

Smart ID Physical Access Module

BaseProcCreateActivateContractor					Create contractor
BaseProcCreateActivateEmployee						Create employee
BaseProcReactivateEmployee							Reactivate employee
BaseProcReactivateEmployeeWithRoleUSSP				Reactivate employee
PcmProcActivateContractorCard						Activate employee card
PcmProcActivateEmployeeCard							Activate employee card
PcmProcAssignNonPersonalCard						Assign non personal card
PcmProcAssignNonPersonalCardToEmployee				Assign Non Personal Card To Employee
PcmProcDeactivateContractor							Deactivate contractor
PcmProcDeactivateContractorCard						Deactivate contractor card
PcmProcDeactivateEmployee							Deactivate employee
PcmProcDeactivateEmployeeCard						Deactivate employee card
PcmProcLockContractorCard							Lock contractor card
PcmProcLockEmployeeCard								Lock employee card
PcmProcReactivateEmployeeCard						Reactivate employee card
PcmProcReactivateEmployeeWithRoleUSSP				Reactivate employee with Role USSP
PcmProcReplaceEmployeeCard							Replace employee card	
PcmProcWithdrawNonPersonalCard						Withdraw non personal card
PcmSubProcReplaceEmployeeCard						Subprocess Replace employee card

PemProcCreateAccessRule								Create access rule
PemProcDeleteAccessRule								Delete access rule
PemProcDeleteGroup									Delete group
PemProcEditAccessRule								Edit access rule
PemProcWithdrawGroupMembership						Withdraw group membership
PemSubProcGenerateExpression						Subprocess Generate expression

Option 2 - Enable PRIME 3.11 to work with the previous custom-beans

Since the old beans will be removed in the future, it is recommended that you make a plan to adapt the processes to the new service task, according to option 1. No date is set yet, for when beans will be removed.

Take a backup of the existing custom beans files in this folder:

Example: custom beans file folder
```
<...>\webapps\prime_explorer\WEB-INF\classes\spring 
```
Copy the following custom beans files:
These files are only to be used when upgrading PRIME to 3.11.

custom-beans-PSTM.xml
custom-beans-PEM.xml
custom-beans-PCM.xml
custom-beans-BIM.xml
custom-beans-SCM.xml
Place the files in this folder:

Example: custom beans file folder
```
<...>\webapps\prime_explorer\WEB-INF\classes\spring 
```
If you had created your own beans, copy them from the old to the new custom beans files.
Restart Tomcat.

Card Production task via Personal Desktop App

As a successor solution for JPKIEncoder, PKI-only Card Encoding via "Production Task" can now be done via Personal Desktop App.

Therefore, the option JPKIEncoder in the Card Template configuration has been removed. The option Personal Desktop App is now available instead in the corresponding drop-down list.

If you currently use the JPKIEncoder, with previous PRIME releases, we recommend that you switch to Personal Desktop App. Configurations that are not changed after the update to PRIME 3.11 (and still have JPKIEncoder set) will fall back to a Card SDK Encoding.

Card job PKI encoding via Personal Desktop App in PRIME Explorer

PRIME Explorer now supports using Personal Desktop App for encoding in the Card Operation ("cardjob") task. This requires that the device ID in the the encoding description file (the DSC file) to be set to 8711 instead of the default 8710. Otherwise Card SDK will be used.

In the encoding description file, specify as follows:
```
[Encoding]
Type=1024,Chip
Devices=8711
...
```

Do not re-use encodings with device ID 8711 for card production with Card SDK. This ID is not supported by the Card SDK and will cause errors.

For PRIME Self-Service, the device ID is irrelevant as it only supports chip encodings via Personal Desktop App.

Integrated EJBCA connector as internal PKI connector

The EJBCA connector has been changed to an integrated connector, similar to all the other PKI connectors. The separate WAR file is no longer available. Customers using the old connector in previous releases have to change their configuration:

Open the corresponding connection in PRIME Designer > Certificate Authorities.
Select EJBCA in the Connection Type drop-down list.
Upload the configuration file, enter Host name and Officer PIN according to the instructions in Integrate Identity Manager with EJBCA connector.

A sample configuration file is available in the PRIME modules ZIP in the subfolder "ca_connector_configs".

DataSyncProxy configuration has changed

The configuration of the DataSyncProxy on client/customer side has been changed.

The custom.properties file from the previous releases has been replaced by the data_sync_proxy.yaml file. A sample is part of the release.

See also Smart ID Agent (DataSyncProxy) in Identity Manager for more information.

Parameter change in service task Core Objects: Create Relation

To keep the old behavior for the service task Core Objects: Create Relation when upgrading PRIME to 3.11 you must do these parameter changes:

Parameter	Update
source	Keep
destination	Keep
relationTypeToDestination	Remove
relationTypeToSource	Remove
includeRelationTypeToCompareOfObjects	Keep
exceptionIsThrownIfRelationAlreadyExists	Keep
relationType	NEW, set value "DEFAULT" (with all uppercase letters)

When creating a new database or a new tenant, the default value for relationType is "Default". But when upgrading from <= 3.10 the default value is "DEFAULT" - with all uppercase letters.

Parameter	Update
dataPoolName	Keep
objectType	New. Set value from destinationType parameter
destinationType	Remove

Upgrade from < 3.10.1 to >= 3.11.0

Updates in standard service tasks

It is recommended to maintain certificates and PKCS#10 requests in the process map as byte. Both certificates and PKCS#10 request can either be represented in their ASN.1 binary form or as utf-8 bytes of the PEM encoded form.

It is now required to get the data as byte for a number of tasks:
1. Cert: Execute PKCS10 Request (${executePKCS10RequestTask})
  - Attribute:
    - P10RequestFormEntry
2. Cert: Extract PKCS#10 Attributes From Request (${extractPKCS10AttributesFromRequestTask})
  - Attribute:
    - P10RequestFormEntry
3. Personal Messaging: Install Certificates on Personal Mobile (${hermodInstallCertificatesTask})
  - Attributes:
    - signatureCertificate
    - authenticationCertificate
    - deviceEncryptionP10
4. Personal Messaging: Install Certificates on Virtual Smartcard (${pxVscHermodInstallCertificatesTask})
  - Attributes:
    - signatureCertificate
    - authenticationCertificate
    - deviceEncryptionP10
The binary form will now be emitted from a number of tasks:
1. Cert: Execute PKCS10 Request (${executePKCS10RequestTask})
  - Attribute:
    - P10RequestFormResult
2. Personal Messaging: Create Key on Personal Mobile (${hermodKeyCreationTask})
  - Variables in the process map provided by the subsequent event:
    - SIG_P10_VAR
    - AUTH_P10_VAR
    - DEVICE_ENC_P10_VAR
3. Personal Messaging: Create Key on Virtual Smartcard (${pxVscHermodKeyCreationTask})
  - Variables in the process map provided by the subsequent event:
    - SIG_P10_VAR
    - AUTH_P10_VAR
    - DEVICE_ENC_P10_VAR
It's also necessary to do a database update as a new table was introduced.

Additional information

Useful links