Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ableneo/liferay-db-setup-core

OSGi bundle to generate Liferay Portal data (permissions, roles, sites, pages etc.). Takes schemed XML declaration as an input and creates database entries accordingly.
https://github.com/ableneo/liferay-db-setup-core

data-generator db-migration declarative liferay liferay-7 liferay-73 liferay-dxp liferay-portal liferay-portlet liferay7 liferay71 liferay73 xml-configuration xml-schema

Last synced: 28 days ago
JSON representation

OSGi bundle to generate Liferay Portal data (permissions, roles, sites, pages etc.). Takes schemed XML declaration as an input and creates database entries accordingly.

Awesome Lists containing this project

README 

        
= Liferay Portal DB setup core

:liferay-version: 7.4.3.86

:current-db-setup-core-version: 7.4.3860

:TOC:



image:https://maven-badges.herokuapp.com/maven-central/com.ableneo.liferay/com.ableneo.liferay.db.setup.core/badge.svg?color=blue[Maven Central,link=https://search.maven.org/search?q=g:com.ableneo.liferay%20AND%20a:com.ableneo.liferay.db.setup.core]

image:https://github.com/ableneo/liferay-db-setup-core/actions/workflows/build.yml/badge.svg[Build workflow status,link=https://github.com/ableneo/liferay-db-setup-core/actions/workflows/build.yml]

image:https://sonarcloud.io/api/project_badges/measure?project=ableneo_liferay-db-setup-core&metric=alert_status[Quality Gate Status,link=https://sonarcloud.io/dashboard?id=ableneo_liferay-db-setup-core]



Library that allows to automate https://github.com/liferay[Liferay] data setup. It uses XML configuration input to add the data.



== Liferay Portal version compatibility



|===

|Liferay Portal version|DB setup core version



|{liferay-version} |{current-db-setup-core-version} link:https://github.com/ableneo/liferay-db-setup-core/tree/master[source]

|7.3.6 | 7.3.605 link:https://central.sonatype.com/artifact/com.ableneo.liferay/com.ableneo.liferay.db.setup.core/7.3.605[jar] link:https://github.com/ableneo/liferay-db-setup-core/tree/7.3.6[source]

|7.3.5 | 7.3.5 link:https://github.com/ableneo/liferay-db-setup-core/tree/7.3.5[source]

|7.1.2 | link:https://github.com/ableneo/liferay-db-setup-core/tree/b0d4e1d602015b704218c5511277bc87dc7eb9c7[source]

|6.2.5 | link:https://github.com/ableneo/liferay-db-setup-core/tree/1.x[source]



|===



== Usage



. Install the `com.ableneo.liferay.db.setup.core-{current-db-setup-core-version}.jar` bundle in `${liferay.home}/osgi/modules`

. Prepare your own bundle that uses the library as a `provided`/`compileOnly` dependency. For example:

+

.build.gradle

[subs=attributes+]

```groovy

dependencies {

    compileOnly 'com.ableneo.liferay:com.ableneo.liferay.db.setup.core:{current-db-setup-core-version}'

}

```

+

.pom.xml

[subs=attributes+]

```xml



    com.ableneo.liferay

    com.ableneo.liferay.db.setup.core

    {current-db-setup-core-version}

    provided



```



. Prepare xml data configuration. Documentation sits directly in the link:src/main/resources/setup_definition.xsd[setup_definition.xsd] file.

+

.Example documentation

image:doc/xsd-inline-documentation.png[]

+

.Example configuration: setup.xml

[source,xml]

----



     

        

         

            20101 

        

    

    

         

            

                

                

                    

                    

                        

                    

                

            

        

    



----

. Load the XML setup file and run `setup` method on it:

+

[source, java]

----

URL resource = Thread.currentThread().getContextClassLoader().getResource(path);

InputStream setupFile = Objects.requireNonNull(resource, "XML Liferay DB setup file not found in classpath.").openStream();

Setup setup = MarshallUtil.unmarshall(setupFile);

boolean setupSuccess = LiferaySetup.setup(setup);

----



==== Example project



Used primarily for integration testing but may be a good start for your application: link:./com.ableneo.liferay.portal.setup.example/[com.ableneo.liferay.portal.setup.example]



=== How to bundle and execute DB changes for Liferay portal



Bundling XML descriptors and code that will execute them in bundle separate to the 



.Directory layout in bundle project



.Usage in activator class

[source, java]

----

----



=== Configuration header

All data definitions in the setup XML file are applied according to the `configuration` header. The header defines:



. the link:https://learn.liferay.com/dxp/latest/en/system-administration/configuring-liferay/virtual_instances.html[virtual instance] on which the library will modify the data.

. admin user account to be used for data modification



.Automatically selected admin user

[source, xml]

----



  

    



    

        liferay.com

    

  



----



.Specified admin user

[source, xml]

----



  

    [email protected]



    

        liferay.com

    

  

----

=== Features



==== Service Access Policy

link:https://learn.liferay.com/dxp/latest/en/installation-and-upgrades/securing-liferay/securing-web-services/setting-service-access-policies.html#[Service access policy] is a link:https://learn.liferay.com/dxp/latest/en/installation-and-upgrades/securing-liferay/securing-web-services.html[second] from four of Liferay's API security layers. Together with _IP Permission Layer_, _Authentication and verification layer_ and _User permission layer_ is responsible for securing access to web services provided by portal instance.



If you develop new link:https://learn.liferay.com/dxp/latest/en/headless-delivery/apis-with-rest-builder.html[REST Builder] REST/GraphQL endpoint's it's a common requirement to setup an access for those API's for an unauthenticated portal user- Guest which is by default forbidden.



.Add new or update existing Service Access Policy by name

[source, xml]

----



    

        

            

             <1>

                com.liferay.headless.admin.user.internal.resource.v1_0.SiteResourceImpl#getSite

            

        

    



----

<1> `allowed-service-signatures` provides the same functionality as link:https://learn.liferay.com/dxp/latest/en/installation-and-upgrades/securing-liferay/securing-web-services/setting-service-access-policies.html#creating-a-service-access-policy[_Advanced Mode_]



.Delete existing Service Access Policy by name

[source,xml]

----



    

        

    



----

==== Permissions

Resource permissions.

[source, xml]

----



    

        

            

            

        

    



----

Resource permissions are set per company are verifiable with followin API call.

[source, java]

----

permissionChecker.hasPermission(

            groupId,

            "my.custom.resource.string",

            companyId,

            "SPECIAL_PERMISSION"

        );

----



Portlet permissions.

[source, xml]

----



    

        

            

            

        

    



----

==== Roles

[source, xml]

----



    

    



----

==== Expando attribute

Following snippet creates expando attribute `canonical-url` with permissions to view by guest user.

[source, xml]

----



    

        

    



----

==== Site

Site element must always have `site-friendly-url` attribute. Guest site is determined by `default` attribute with `true` value. All content like *pages*, *articles*, *documents* etc. is always created within a specific site.

[source, xml]

----



    

    

    

        Admin

        

    



----

==== Journal Article structure and template

Files `new_structure.xml` and `new_structure_template.ftl` are deployed as a part of a module that is using the `db-setup-core` library and reside in it's classpath.

[source, xml]

----



    

      



      



      Admin

    

----

==== Articles

File `artcle.xml` is deployed as a part of a module that is using the `db-setup-core` library and reside in it's classpath.

[source, xml]

----



    

        

            

        

    



----

==== Document

Document's file itself is determined by `file-system-name` attribute which defines resource on classpath.

[source, xml]

----



    

        

    



----



=== Liferay Portal requirements



The code is compatible with *Liferay Portal {liferay-version}*. Other versions that have been or are supported:



. https://github.com/ableneo/liferay-db-setup-core/tree/7.3.6[Liferay Portal EE/CE 7.3.6]

. https://github.com/ableneo/liferay-db-setup-core/tree/7.3.5[Liferay Portal EE/CE 7.3.5]

. https://github.com/ableneo/liferay-db-setup-core/tree/b0d4e1d602015b704218c5511277bc87dc7eb9c7[Liferay Portal EE/CE 7.1.2]

. https://github.com/ableneo/liferay-db-setup-core/tree/1.x[Liferay Portal EE/CE 6.2.5 and higher]



== Roadmap



* integration with link:https://liferay.dev/es/blogs/-/blogs/site-initializers-101[Site Initializers]

* more tests

* project integration with lundegaard fork: https://github.com/lundegaard/liferay-db-setup-core, until than changes and fixes from lundegaard fork will be ported to the library



== Motivation



We use https://github.com/liferay[Liferay] as an application building platform.



Portlets, content and permissions, in short- *data* serve as a building block of a web application with consistent portal UX. In the use case the *data* play important role in application building, greatly influencing UX.



By storing the application *data* as XML declaration we enable developers to version and progress *data* development as if it was a *code*. All standard development practices like versioning, code review, building and deployment can be applied to the Liferay *data as code*.



== Contributing



Want/need to hack on db-setup-core? See our link:CONTRIBUTING.adoc[super short contributing guide] for information on building, testing and contributing changes.



They are probably not perfect, please let me know if anything feels wrong or incomplete.



== Changelog



=== Version 7.4.3860



==== Features & bug fixes

* switched to JDK11

* upgraded and tested all features in link:./com.ableneo.liferay.site.example/src/main/resources/setup-ableneo-site.xml[example setup] with Liferay Portal 7.4.3.86

* attached two tests from lundegaard fork, credit goes to link:https://github.com/Jandys[Jakub Jandak], thank you!



==== Refactorings & project changes

* improved documentation



=== Version 7.3.605

==== Features & bug fixes

* fixed bug when handling multiline link:https://learn.liferay.com/dxp/latest/en/installation-and-upgrades/securing-liferay/securing-web-services/setting-service-access-policies.html[service access policy]



=== Version 7.3.604

==== Features & bug fixes

* added an ability to create/update/delete link:https://learn.liferay.com/dxp/latest/en/installation-and-upgrades/securing-liferay/securing-web-services/setting-service-access-policies.html[Service Access Policies]



==== Refactorings & project changes

* refactored common mock setup into a separate class



=== Version 7.3.603

==== Features & bug fixes

* fixed setup for multiple companies/groups



==== Refactorings & project changes

* upgraded test harness to latest mockito, added basic tests for multiple company/groups setup execution

* fixed SonarCloud scan integration with GitHub actions, TODO: pull request decoration



=== Version 7.3.602

==== Features & bug fixes

* fixed configuration related resource reading, library can read e.g. article files from caller bundle, credit goes to Milan Kuljovsky- thank you!

* article-structure-key and article-template-key article element attributes are required as there are no defaults for those values



=== Version 7.3.601

==== Features & bug fixes

* target Liferay Portal version is still minimum 7.3.6 (GA7)

* fix: add individual resource for permissions setup in case there are declared not for portlet but a `model-resource`, allows to use `hasUserPermission` method for the custom resource id string and a `primKey = companyId`

+

.Fixed configuration

[source, xml]

----

    

        

            

                

----



==== Refactorings & project changes

* version changed from 4 to 3 numbers, build version will increment every time there is a new feature or bugfix

* improved docs



=== Version 7.3.6.0



==== Features & bug fixes

* Bumped target Liferay Portal version to minimum 7.3.6 ga7.

* Improved category/vocabulary idempotency, it's possible to update categories and vocabularies with optional uuid, before categories/vocabularies were identified only by name. That allows to update a category name which wasn't possible before.

* Improved categories/vocabulary updates performance, update is only issued if anything in the definition differs compared to the data in the DB.

* Category by_name search is scoped only to a particular vocabulary.

* Added property element in categories that allows to define AssetCategoryProperty. These are identified by a key. 

+

TIP: TODO: deletion of existing property.



==== Refactorings & project changes

* divided xsd to "elements" and "types" parts, replaced many element references with types which improves naming flexibility

* every xsd type follows is camel cased and suffixed with word: Type, e.g. UuidType

* simplified dependency management with `release.portal.bom`

* removed `shade` maven plugin as portal exports `com.liferay.portlet.asset.util` package already in `org.eclipse.osgi_3.13.0.LIFERAY-PATCHED-11` bundle



=== Version 7.3.5.0



==== Features & bug fixes



* OSGI descriptors in JAR, the bundle can be deployed and work as a standalone Liferay 7.x bundle



* instance import feature added, credit goes to https://github.com/bimki[@bimki] - thank you!

* portal properties feature added, credit goes to https://github.com/fabalint[@fabalint] - thank you!

* new helper methods to run the setup (ported from 1.x branch):

** `com.ableneo.liferay.portal.setup.LiferaySetup#setup(java.io.InputStream)`

** `com.ableneo.liferay.portal.setup.LiferaySetup#setup(java.io.File)`

* fixed categorization idempotency (vocabulary and category name handling)

* fixed language handling for groups



==== Refactorings & project changes



* improved javadoc in entrypoint `com.ableneo.liferay.portal.setup.LiferaySetup` class

* upped dependencies to https://liferay.dev/blogs/-/blogs/liferay-portal-7-3-ce-ga6-release[Liferay 7.3.5], credit goes to https://github.com/fabalint[@fabalint] - thank you!

* changed versioning so that major.minor.patch version reflects target platform, build version will be used to track changes in the library

* documentation format conversion from markdown to https://asciidoc.org/[aciidoc]

* added slf4j and changed logger in few classes for more ergonomic log message interpolation (Liferay 7.x provides slf4j by default)

* added prettier formatter to the project

* added build environment setup automation with <<_automated_local_build_environment_setup_with_nix,nix>>



=== Version 2.2.0-SNAPSHOT



==== Features & bug fixes



* it's possible to use more than one company id per configuration file, the configuration will be applied to all listed companies

* tag names in configuration follow unified naming convention: word-word

* run-as-user renamed to run-as-user-email to be explicit about expected value

* added missing documentation to few xml elements

* setup xsd provides a version attribute



==== Refactorings & project changes



* configured sonar analysis on each commit

* configured maven test / coverage runner

* maven project structure has changed to single-module

* companyId, groupId and runAsUserId are set in Setup class and propagated to all involved Utils with SetupConfigurationThreadLocal context class

* improved MarshallUtil performance

* introduced unit tests

* most of the problems reported by sonar are fixed

* improved logging



=== Version 2.1.4



==== Features & bug fixes



* Added resource class name when creating ADT

* Fix user expando assignement

* Allow add categories and summaries to articles