Basic application skeleton you can create by archetype, please follow this tutorial: Archetype tutorial.
CzechIdM is a modular application built by Maven. Modules often have really similar structure consisting of:
In this tutorial we will describe the currently preferred way of setting up a CzechIdM module. Some basic information about developing the module can be found also in the Developer Guide - Quickstart.
The Java code typically handles all the business logic and heavy lifting in the application. There are multiple areas of interest you will probably need while developing a module:
Keep all Java sources under src/main/java directory and keep package structure as eu/bcvsolutions/idm/#yourmodulename#.
Setting default module configuration is crucial. The default configuration is loaded from the application*.properties files, which will be discussed later. You can override the values in the properties by defining you own props in the application, which get stored in the database and have higher priority over the configuration files.
For accessing the properties, create a Spring bean extending the Configurable interface. See example implementation of module configuration, or EmailerConfiguration and its implementation DefaultEmailerConfiguration as an example. Creating a strongly typed configuration bean will give you great flexibility - you can use whatever types you need without being forced to parse the props from strings every time you need it.
It is advised to keep the configuration logic in the config Java package.
Event processors are a powerful mechanism in customizing your CzechIdM deployment. All major entities, such as IdmIdentity, supports events. Use case example: sending notification to administrator after an identity has been created:
IdentityEventType.CREATE eventsprocess methodThat's it. Without the need to modify any of the existing code or the core module we have modified the behavior of the application.
This way you can alter entities processing, provisioning and many other cases.
Events also carry event properties. You can use such properties to cancel provisioning, for example, by the following code:
SysProvisioningOperation op = event.getContent(); op.setResultState(OperationState.CANCELED); provisioningOperationService.delete(op); return new DefaultEventResult<>(event, this, true);
Turning modules on and off is also possible in runtime by configuration, see the CzechIdM wiki for details.
It is advised to keep all processors in the event Java package and sub-packages.
Extending entities in CzechIdM could be simply done by defining EAV attributes. These are referred by plain String keys in the code, which may become troublesome for larger modules, simply because magic values and restatements are generally a bad idea.
To keep EAV references type typo-safe, create a classic Java enum, which accepts two strings as constructor params. Example:
public interface EavConstants { String getEavCode(); PersistentType getPersistentType(); } public enum MyIdentityConstants implements EavConstants { MY_CUSTOM_SOMETHING("myCustomSomethingEav", PersistentType.TEXT), MY_ATTRIBUTE("myAttrEavCode", PersistentType.TEXT); // fields private final String eavCode; private final PersistentType persistentType; MyIdentityConstants(String eavCode, PersistentType persistentType) { this.eavCode = eavCode; this.persistentType = persistentType; } @Override public String getEavCode() { return eavCode; } @Override public PersistentType getPersistentType() { return persistentType; } }
With such setup you can reference all your module-specific EAVs as MyIdentityConstants.MY_ATTRIBUTE. Another advantage of this approach is creating attribute definitions on application startup.
It is advised to keep the the EAV attributes definitions in the constants Java package.
To ensure our module is easily runnable even on the first time it's deployed, we need to initialize module-specific data. That is done through Spring application event listener. This is highly recommended at least for creating EAV attribute definition (+ beneficial for tests, which start with empty database and we need to initialize the definitions somowhere). Following example show such bean, which creates EAV definitions for our MyIdentityConstants enum and create a role for notifications:
@Component @DependsOn("initApplicationData") public class InitMyModuleData implements ApplicationListener<ContextRefreshedEvent> { @Autowired private SecurityService securityService; @Autowired private FormService formService; @Autowired private IdmRoleService roleService; @Autowired private MyConfiguration configuration; @Override public void onApplicationEvent(ContextRefreshedEvent event) { init(); } public void init() { // system auth. to get full permissions securityService.setSystemAuthentication(); // try { for (EavConstants extAttr : MyIdentityConstants.values()) { createEavAttribute(extAttr, IdmIdentity.class); } // final String organizationsEventRecipientRole = configuration.getNotificationRoleName(); IdmRole orgRecipientRole = roleService.getByName(organizationsEventRecipientRole); if (orgRecipientRole == null) { orgRecipientRole = new IdmRole(); orgRecipientRole.setCanBeRequested(true); orgRecipientRole.setDescription("Role holders receive notifications about our use case."); orgRecipientRole.setDisabled(false); orgRecipientRole.setName(organizationsEventRecipientRole); orgRecipientRole.setPriority(1); orgRecipientRole.setRoleType(RoleType.SYSTEM); roleService.save(orgRecipientRole); } } finally { SecurityContextHolder.clearContext(); } } private void createEavAttribute(EavConstants extAttr, Class<? extends FormableEntity> clazz) { IdmFormAttribute retrieved = formService.getAttribute(clazz, extAttr.getEavCode()); if (retrieved != null) { return; } // IdmFormAttribute attr = new IdmFormAttribute(); attr.setCode(extAttr.getEavCode()); attr.setName(extAttr.getEavCode()); attr.setPlaceholder(extAttr.getEavCode()); attr.setPersistentType(extAttr.getPersistentType()); formService.saveAttribute(clazz, attr); } }
Generally, all base classes for testing your module should be available out-of-the-box in the czechidm-test-api module, which you need to include as your module's dependency.
The only exception is for testing Activiti's workflows. For that reason, we need to create ActivitiRule bean first. Create following bean under the test sources module directory:
@ActiveProfiles("test") @Configuration public class MyModuleTestConfiguration { @Bean public ActivitiRule activitiRule(ProcessEngine processEngine) { return new ActivitiRule(processEngine); } }
In version 7.3 it is also necessary to have dependency on core-impl module and create a base class for workflow testing. Following is a functioning example:
public abstract class AbstractMyModuleWorkflowIntegrationTest extends AbstractWorkflowIntegrationTest { @Override public DefaultActivityBehaviorFactory getBehaviourFactory() { return new CustomActivityBehaviorFactory(); } }
With such setup you should be able to test Activiti workflows without any problems. For test example please refer to HistoryProcessAndTaskTest.
Groovy scripts are used primarily as transformations while connecting end-point systems.
It is advised to keep all your custom scripts the src/main/resources/#package#/scripts directory of your module. Please do version the scripts, do not leave them only in the application! This is crucial for maintenance and upgrade reasons. XML is now a preferred script format, see IdmCoreGetFullName and IdmScript.xsd.
Keep notification templates in the src/main/resources/#package#/templates directory. For an example of core template, see IdmCoreChangeIdentityRole and IdmNotificationTemplate.xsd.
Activiti workflows are typically kept in the src/main/resources/#package#/workflows directory. Workflows are deployed and versioned automatically.
To test workflows, please see the Setting up test suites chapter.
While connecting endpoint systems through scripted connectors (mostly), we have to either deploy these scripts with CzechIdM or we just simple need to version these scripts. The preferred way is to keep all connector scripts in the src/main/resources/#package#/scripts directory and sub-directories, however use whatever works best for you.
Please do version the scripts, do not leave them only in the application or on the server file system! This is crucial for maintenance and upgrade reasons.
For example of JDBC script development see the usage of Scripted SQL connector.
Database migration (done by Flyway) is an important part of every db-backed application (module here) maintenance. Each module has its own Flyway configuration. To setup yours, follow the guide in wiki.