The Script Portlet command line application is a client-side tool that is used to automate the upload of HTML, JS, and CSS-based web applications to WebSphere Portal to create and update Script Portlets. The tool simplifies the development process by allowing a user to push the contents of a web application from their local directory to a script portlet instance in a Web Content Manager site area. If the specified script portlet instance exists, the content that is pushed from the directory replaces any content that is already associated with the script portlet. The tool is an alternative to using a browser to import and edit content on a portal page. The tool’s design makes it easy to start from a command line or from an integrated development environment (IDE) to support an iterative code and test development style.
In a nutshell, the command line utility allows you to:
- Push applications from a directory on the local file system to content items in Web Content Manager site areas for use as Script Portlets
- Specify default configuration settings (host:port, default site area, user name, etc) that are common across applications
- Specify application-specific configuration settings (for example, web content item name) in each application folder
- Specify a portal project and virtual portal to use
- Override settings with command line arguments, for those cases where you need to specify a unique value for a specific run
The use of these features and options are described in the rest of this document.
This documentation assumes that the reader is familiar with IBM WebSphere Portal (logging in, creating pages and adding portlets). It also assumes that the reader has installed Script Portlet to IBM WebSphere Portal (recommended version 8.5 CF05 or later) as described here.
The command line utility is supported on and provides shell script wrappers for use with Windows, Mac, and Linux systems.
Extract the command line tool to an appropriate folder on your local filesystem and set your command path to include this new folder location, as described here.
One of the best new features of the Script Portlet command line utility is the ability to configure default settings in a sp-config.json configuration file in the folder where the utility is installed. This feature minimizes the use of command line arguments. The feature makes repetitive use of the tool for rapid development and publishing trivial, and makes integration with external tools (editors, source watchers etc.), even simpler.
This document assumes that you are using a single portal server for your development and testing of script portlet applications. Before you start using the tool, set the following properties in the sp-config.json file in the folder where you installed the script portlet command line utility. This configuration file provides the default settings that are used to determine the push commands options, unless overridden by an application-specific sp-config.json (described later in this document) or by optional explicit command line arguments.
The default sp-config.json provided with the Script Portlet command line tool provides inline comments that describe each of the configuration options that can be set there. At a minimum, it is recommended that you set values for the following, in the default sp-config.json file if you are using the same server and user name for pushing each application.
Server to publish to
“scriptPortletServer” : “http://hostname:port”,
Portal Server user to authenticate as
Portal Server password
If you are using a local (non-secure, non-sensitive) developer only portal instance, then you can set portalPassword in this file too. However, this setting stores the password in clear text in a configuration file, which is not a security best practice and should not be used for any secure or sensitive servers and never for staging and production servers. Leaving the password out of the configuration file does prompt you each time that you run the command for the password. You can specify a command line argument to avoid the prompt. However, it is a reasonable tradeoff between a little more work to ensure a lot more security than storing a password as clear text.
Default Site Area
By default, the configuration file specifies “Script Portlet Library/Script Portlet Applications” as the site area to push new applications to and to update applications in. The wcmContentName configuration property or command line argument must be specified when you push an application. This site area is provided with the Script Portlet installation to ease the getting started process for new developers. Advanced users might want to create their own WCM library and site area for storing applications in, along with setting access control on the custom site area. See the WCM and Script Portlet documentation for information on creating site areas for use with Script Portlet and the content toolbar.
“wcmSiteArea”: “Script Portlet Library/Script Portlet Applications/”,
By providing the above initial setup values, you can reduce the complexity of the command line push down to minimal arguments necessary for each execution.
Application Specific Configuration
As previously mentioned, the default sp-config.json provided with the command line utility provides the fallback configuration settings if not overridden by an application-specific sp-config.json or by command line arguments. It is best to provide the common portal server information in that default sp-config.json and then to provide the wcmContentName for each application as a configuration setting in an application-specific sp-config.json within the application folder.
In the root folder of each application that you want to push, create an application specific sp-config.json with the following contents:
“wcmContentName” : “nameOfYourApplication”
To override any other settings, separate them with a comma, with the same syntax found in the default sp-config.json
How Simple Can It Get?
If you set the scriptPortletServer and portalUser in the default sp-config.json with the command line tool and the application content name in the application specific sp-config.json, then all you need to do to push your application to the server now is run it.
If you stored your password in the configuration file, that is all you need to do and the rest is supplied by the configuration. If you chose not to store your password in the configuration file, then you will be prompted for the portal user’s password at this point. You can also specify it with the -portalPassword argument on the command line. All other arguments would come from the two sp-config.json configuration files.
Command Line Options
As mentioned earlier, the sp-config.json configuration (application specific, then default fallback) is used unless overridden by command line argument. Most of the settings in the sp-config.json configuration files can be overridden by command line argument, which is pretty much just the configuration option itself preceded by a hyphen (eg, -portalPassword=mypassword ). I say “most” rather than all, because you wouldn’t want to try to specify the list of excluded file names as a command line argument anyway.
For a complete list of the current command line options, please refer to the command line help here.
If you forget an option and don’t have the help link handy, you can execute “sp” with no arguments and it will log a usage statement with the available commands and command line arguments, and “sp help” will display detailed information about each argument.
WebSphere Portal provides the concept of projects to help manage updates to content, and thus script portlets, draft versions and publishing of those drafts when ready. In order to specify that an application should be pushed in a “draft” state, associated with an existing portal project on your server, you may specify the “projectID” configuration option, either in your application specific sp-config.json for a given app, or via command line option -projectID “myproject”.
Specifying a Virtual Portal
If your applications should all be associated with a particular named virtual portal, then it’s best to set the “virtualPortalID” parameter in the default sp-config.json configuration file for the command line utility, to the name of the virtual portal. To specify a virtual portal for a single application push only, you may specify -virtualPortalID “virtualPortalName” as a command line argument to override the configuration.
Integrating with external tools
The command line utility presented here goes a long way toward making life easy for single page web application developers to leverage their existing skills and tools, to develop applications for script portlet and WebSphere Portal. Running the “sp push” task repeatedly, whether manually or with a build task, could get a little monotonous after a while.
A related article provides a great description of how you may configure an Eclipse build to kick off an sp push each time a web project is built, providing automatic publishing of your application to the server when the project is built. While we do not expect every developer to use Eclipse for their script portlet development, this introduction to development tool integration provides a great start for learning what you might need to do to integrate with your own choice of development tools.
An interesting blog post provides an introduction into how a Script Portlet developer used the open source Gulp utility to watch changes to a web application folder and automatically execute “sp push” of an application each time changes were made to the application.
Once you’ve mastered the above, and have tried out building and pushing your first script portlet applications, it’s time to start thinking about the rest of the development process.
Please see the related article on “Script Portlet and Source Code Management“ for more information on integrating your development and pushing of applications with source control management and how to deal with migration of your application between test, staging and production systems here.
Now that you have learned how to set up your environment, build, push and manage versions of your script portlet applications, it’s a good time to learn more about the best practices for developing script based applications for use in a multi-portlet portal page environment.
- Product Documentation – Script Portlet Command Line Push
- Script Portlet Command Line Push Integration with External Editors
- Blog post by a Script Portlet user – Automatically Push Changes to the Script Portlet with Gulp Watch