ableneo/liferay-db-setup-core

BranchesTags

Repository files navigation

Table of Contents

Maven CentralBuild workflow statusQuality Gate Status

Library that allows to automate Liferay data setup. It uses XML configuration input to add the data.

Liferay Portal versionDB setup core version

7.4.3.125

7.4.3125.0 source

7.4.3.86

7.4.3861 jar source

7.3.6

7.3.605 jar source

7.3.6

7.3.605 jar source

7.3.5

7.3.5 source

7.1.2

source

6.2.5

source

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

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

    build.gradle
    dependencies {
    compileOnly 'com.ableneo.liferay:com.ableneo.liferay.db.setup.core:7.4.3125.0'
}
    pom.xml
    <dependency>
    <groupId>com.ableneo.liferay</groupId>
    <artifactId>com.ableneo.liferay.db.setup.core</artifactId>
    <version>7.4.3125.0</version>
    <scope>provided</scope>
</dependency>

  3. Prepare xml data configuration. Documentation sits directly in the setup_definition.xsd file.

    Example documentation

    xsd inline documentation

    Example configuration: setup.xml
    <?xml version="1.0" encoding="UTF-8" ?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
    <configuration>
        <!-- uses random administrator account for the setup in the company, run-as-user-email tag allows to specify particular admin account to be used for the setup -->
        <company>
            <companyid>20101</companyid> <!-- companywebid can be used alternatively -->
        </company>
    </configuration>
    <sites>
        <site> <!-- Guest by default -->
            <vocabulary name="Some categories" uuid="602f55b6-6021-455e-8d6d-696cc25daa91">
                <title-translation locale="de_DE" text="Einige Kategorien"/>
                <category name="Other categories" uuid="867b33df-2465-4a81-9945-88159c604589">
                    <title-translation locale="de_DE" text="Andere Kategorien"/>
                    <category name="New category" uuid="5fb4308e-bd21-4cf4-bdc5-3557508ffe4a">
                        <title-translation locale="de_DE" text="Neue Kategorie"/>
                    </category>
                </category>
            </vocabulary>
        </site>
    </sites>
</setup>

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

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

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

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

Usage in activator class
All data definitions in the setup XML file are applied according to the configuration header. The header defines:
  1. the virtual instance on which the library will modify the data.
  2. admin user account to be used for data modification
Automatically selected admin user
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
  <configuration>
    <!-- run as automatically selected admin -->

    <company>
        <companywebid>liferay.com</companywebid>
    </company>
  </configuration>
</setup>
Specified admin user
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
  <configuration>
    <run-as-user-email>[email protected]</run-as-user-email>

    <company>
        <companywebid>liferay.com</companywebid>
    </company>
  </configuration>
</setup>
Service access policy is a 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 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
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
<company-settings>
    <service-access-policies>
        <service-access-policy name="MY_ACCESS_POLICY" enabled="true" unauthenticated="true">
            <title locale="sk_SK" text="Moja pristupova politika" />
            <allowed-service-signatures> (1)
                com.liferay.headless.admin.user.internal.resource.v1_0.SiteResourceImpl#getSite
            </allowed-service-signatures>
        </service-access-policy>
    </service-access-policies>
</company-settings>
</setup>
  1. allowed-service-signatures provides the same functionality as Advanced Mode
Delete existing Service Access Policy by name
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
<company-settings>
    <service-access-policies>
        <delete-service-access-policy name="WIZARD_GUEST_ACCESS"/>
    </service-access-policies>
</company-settings>
</setup>
Resource permissions.
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
<resource-permissions>
    <resource resource-id="my.custom.resource.string">
        <actionId name="SPECIAL_PERMISSION">
            <role name="My Role"/>
            <role name="Your Role"/>
        </actionId>
    </resource>
</resource-permissions>
</setup>
Resource permissions are set per company are verifiable with followin API call.
permissionChecker.hasPermission(
            groupId,
            "my.custom.resource.string",
            companyId,
            "SPECIAL_PERMISSION"
        );
Portlet permissions.
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
<resource-permissions>
    <resource resource-id="myportlet_WAR_portlets">
        <actionId name="VIEW">
            <role name="User"/>
            <role name="Guest"/>
        </actionId>
    </resource>
</resource-permissions>
</setup>
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
<roles>
    <role name="Regular Role"/>
    <role name="Site Role" type="site"/>
</roles>
</setup>
Following snippet creates expando attribute canonical-url with permissions to view by guest user.
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
<custom-fields>
    <field name="canonical-url" type="string" class-name="com.liferay.portal.kernel.model.Layout">
        <role-permission role-name="Guest" permission="view"/>
    </field>
</custom-fields>
</setup>
All content like pages, articles, documents etc. is always created within a specific site. You can create new or refer to existing site.
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">
<sites>
    <site default="true">
        <!-- default company site -->
    </site>
    <site global="true">
        <!-- global company site -->
    </site>
    <site default="false" site-friendly-url="/admin" name="Admin">
        <!-- specific site -->
        <name-translation locale="en_US" text="Admin"/>
    </site>
</sites>
</setup>
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.
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">

<sites>
    <site site-friendly-url="/admin" name="Admin">
      <article-structure key="NEW-STRUCTURE-KEY"
                         path="new_structure.xml"
                         name="New Structure"/>

      <article-template key="NEW-STRUCTURE-TEMPLATE-KEY"
                        path="new_structure_template.ftl"
                        article-structure-key="NEW-STRUCTURE-KEY" name="New Structure Template" cacheable="true"/>

    </site>
</sites>
</setup>
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.
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">

<sites>
    <site global="true">
        <article
            title="Article Title"
            path="article.xml"
            article-structure-key="NEW-STRUCTURE-KEY"
            article-template-key="NEW-STRUCTURE-TEMPLATE-KEY"
            articleId="ARTICLE_ID">
            <tag name="product" />
        </article>
    </site>
</sites>
</setup>
Document’s file itself is determined by file-system-name attribute which defines resource on classpath.
<?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">

<sites>
    <site name="Guest">
        <document file-system-name="image.svg"
                  document-folder-name="/Images"
                  document-filename="image.svg"
                  document-title="image.svg"/>
    </site>
</sites>
</setup>
The code is compatible with Liferay Portal 7.4.3.125. Other versions that have been or are supported:
We use 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.
Want/need to hack on db-setup-core? See our 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.
  • switched to JDK21
  • api compatible with Liferay 7.4.3.125
  • fixed category import (updating parent)
  • fixed working with global/default sites [_site_selection]
  • updated docs
  • switched to JDK11
  • upgraded and tested all features in example setup with Liferay Portal 7.4.3.86
  • attached two tests from lundegaard fork, credit goes to Jakub Jandak, thank you!
  • improved documentation
  • refactored common mock setup into a separate class
  • fixed setup for multiple companies/groups
  • upgraded test harness to latest mockito, added basic tests for multiple company/groups setup execution
  • fixed SonarCloud scan integration with actions, TODO: pull request decoration
  • 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
  • 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
    <?xml version="1.0" encoding="UTF-8"?>
<setup xmlns="http://www.ableneo.com/liferay/setup">

    <resource-permissions>
        <resource resource-id="custom.resource.id-not.a.portlet.id">
            <actionId name="SOME_PERMISSION">
                <role name="Some Portal Role"/>
            </actionId>
        </resource>
    </resource-permissions>
</setup>
  • version changed from 4 to 3 numbers, build version will increment every time there is a new feature or bugfix
  • improved docs
  • 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.
  • 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-ED-11 bundle
  • 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 @bimki - thank you!
  • portal properties feature added, credit goes to @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
  • improved javadoc in entrypoint com.ableneo.liferay.portal.setup.LiferaySetup class
  • upped dependencies to Liferay 7.3.5, credit goes to @fabalint - thank you!
  • changed versioning so that major.minor. version reflects target platform, build version will be used to track changes in the library
  • documentation format conversion from markdown to 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 nix
  • 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
  • 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
  • Added resource class name when creating ADT
  • Fix user expando assignement
  • Allow add categories and summaries to articles
About
OSGi bundle to generate Liferay Portal data (permissions, roles, sites, pages etc.). Takes schemed XML declaration as an input and creates database entries accordingly.
Topics
declarative xml-schema data-generator liferay xml-configuration db-migration liferay-portal liferay-portlet liferay-dxp liferay7 liferay-7 liferay71 liferay73 liferay-73
Resources
 Readme
License
 MIT license
 Activity
 Custom properties
Stars
 4 stars
Watchers
 5 watching
Forks
 6 forks
Report repository
Releases
 16 tags
Packages 
No packages published
Contributors 8
Languages