This is a multi-module Maven project.
Here's what you get:
hrs-portlets-api: an API!hrs-portlets-webapp: a webapp! Which uses the API! But includes no implementation of the API!hrs-portlets-bnsemail-impl,hrs-portlets-cypress-impl,hrs-portlets-ps-impl: implementations of the API!hrs-portlets-demo-impl: a no-dependencies demo-data implementation of the API!hrs-portlets-local-example: an example of what you're supposed to do to implement this locally!
So, here's how this works.
There's an API module that defines the programming interface.
There's implementations of that interface.
There's a web application that relies on the API. That hrs-portlets-webapp module builds a .war portlet web application. But that web application includes no implementation of the API, so it won't actually work. That's because you're not intended to deploy this portlet web application as is. Rather, you're intended to overlay upon it locally, at the least to declare dependencies on your favorite implementations.
That's a bit complicated, so there's an example of doing this. The hrs-portlets-local-example module is an example of what you need to do to build your very own build of this portlet, including the specific implementation .jars that you'd like to use. Out of the box the example demonstrates pulling in the no-dependencies demo implementation of the API, so as a bonus, you can build the example as-is, deploy it to your favorite portal, and see the HRS portlets in action. You're welcome.
Assuming you have a proper JDK and Maven installation,
mvn install
executed in this directory right alongside this README will build the project from source.
There will resultingly be a file
{this_directory}/hrs-portlets-local-example/target/hrsportlet.war
Deploy that .war file to your favorite portal. That typically involves using portal-specific tooling to re-write the portlet.xml into generated web.xml declarations, registering the portlet in your portal, and adding it to a layout such that some user actually sees it. Documentation of how to do all that is out of scope of this portlet README but is presumably well documented for your portal platform of choice.
Well. That depends on what human resources systems you're integrating with.
But roughly it goes like this:
Put it somewhere that makes sense for you. It's going to be yours, specific to your implementation for your portal. In source control in GitHub is a pretty good idea. You could name it something like "hrs-portlets-miskatonic-university", varying that for whatever university you're really doing it for.
It's going to contain only the recipe for your very own configuration of the portlet, not a copy of the shared source code etc. It's what's called a "Maven overlay".
Since it's a copy of the example that builds the demo, it should still build the demo and that should still work. You should probably verify this before you start changing things.
Adjust pom.xml . There's commented out examples of how you pull in the real implementation dependencies.
You should also adjust the group and name and so forth to be specific to your university, your implementation. It won't be an example anymore. :)
If your HR system(s) are exactly the ones supported by this portlet, great! I bet you like badgers. Anyway, you then configure those dependencies as documented in the README.md files in each of the relevant -impl modules. As in, in pom.xml you declare the dependency, and then you have to do dependency-specific stuff to configure whatever dependencies you declared, and the dependency-specific stuff is documented specifically in those dependency sub-modules.
If you want to integrate with an HRS implementation other than those for which dependencies already exist, well, you'll need to go build new implementations to depend upon. Go build new modules like the implementations that are already here, and then you can depend upon those shiny new implementations. Maybe you can start from or use parts of the existing implementations.
Now that your local build is configured to depend on your favorite dependencies, maybe even shiny new dependencies that you've invented for the purpose, you can run the build again to get a new build of your customized HRS portlet which uses the implementations of the API that are right for you.
Yeah.
So, here's how this works: the portlet auto-wires in the available implementations of the API.
This will work great if and only if there's exactly one implementation of each needed API available to the portlet.
So, if you declare only the demo implementation, great, that fulfills all the API requirements, those implementations will be used, life is good.
Likewise, if you declare only the bnsemail, cypress, and peoplesoft implementations, as they exist today, great, those .jars just so happen to collectively contain exactly one implementation of each of the needed APIs, so the right implementations will be discovered, life is good.
If you write new implementations and declare those dependencies in your pom.xml so that, again, collectively, there's exactly one implementation of each API, great, that'll work too.
Woe unto you if there's more than one implementation of each API available.
Your controls over this are:
- What you choose to include in your portlet via Maven
pom.xmldeclarations (good practice: include exactly one implementation of each API so that your portlet cannot possibly find the wrong one). - Configuration of the auto-wiring annotation-driven configuration (tedious. not necessary if you're careful about the pom.xml dependencies in (1)).
- Switch away from auto-wiring and explicitly configure instead (you'll hate this. it's a lot of tedious XML. but you'll be able to more explicitly see how the APIs are fulfilled in your portlet implementation).
In /{your_portlet}/src/main/resources/logback.xml
- Update paths in file to where HRS portlet should write its log files.
Note that configuration specific to the particular API implementations is documented in README.md files in the sub-modules for each of those implementations.