Chapter 2. Starting and Stopping OpenIDM

To start OpenIDM interactively, open a terminal or command window, change to the openidm directory, and run the startup script:

• startup.sh (UNIX)

• startup.bat (Windows)

• project location (-p)

  The project location specifies the configuration and default scripts with which OpenIDM will run.

  If you specify the project location, OpenIDM does not try to locate configuration objects in the default location. All configuration objects and any artifacts that are not in the bundled defaults (such as custom scripts) must be provided in the project location. This includes everything that is in the default openidm/conf and openidm/script directories.

  The following command starts OpenIDM with the configuration of sample 1:

  $ ./startup.sh -p /path/to/openidm/samples/sample1

  If an absolute path is not provided, the path is relative to the system property, user.dir. If no project location is specified, OpenIDM is launched with the default configuration in /path/to/openidm/conf.

• working location (-w)

  The working location specifies the directory to which OpenIDM writes its cache. Specifying a working location separates the project from the cached data that the system needs to store. The working location includes everything that is in the default openidm/db and openidm/audit, openidm/felix-cache, and openidm/logs directories.

  The following command specifies that OpenIDM writes its cached data to /Users/admin/openidm/storage:

  $ ./startup.sh -w /Users/admin/openidm/storage

  If an absolute path is not provided, the path is relative to the system property, user.dir. If no working location is specified, OpenIDM writes its cached data to openidm/db and openidm/logs.

• startup configuration file (-c)

  A customizable startup configuration file (named launcher.json) enables you to specify how the OSGi Framework is started.

  If no configuration file is specified, the default configuration (defined in /path/to/openidm/bin/launcher.json) is used. The following command starts OpenIDM with an alternative startup configuration file:

  $ ./startup.sh -c /Users/admin/openidm/bin/launcher.json

  You can modify the default startup configuration file to specify a different startup configuration.

  The customizable properties of the default startup configuration file are as follows:

  • "location" : "bundle" - resolves to the install location. You can also load OpenIDM from a specified zip file ("location" : "openidm.zip") or you can install a single jar file ("location" : "openidm-system-2.1.jar").

  • "includes" : "**/openidm-system-*.jar" - the specified folder is scanned for jar files relating to the system startup. If the value of "includes" is *.jar, you must specifically exclude any jars in the bundle that you do not want to install, by setting the "excludes" property.

  • "start-level" : 1 - specifies a start level for the jar files identified previously.

  • "action" : "install.start" - a period-separated list of actions to be taken on the jar files. Values can be one or more of "install.start.update.uninstall".

  • "config.properties" - takes either a path to a configuration file (relative to the project location) or a list of configuration properties and their values. The list must be in the format "string":"string", for example:

               "config.properties" :
     	           {
     	               "property" : "value"
     	           },
               

  • "system.properties" - takes either a path to a system.properties file (relative to the project location) or a list of system properties and their values. The list must be in the format "string":"string", for example:

               "system.properties" :
     	           {
     	               "property" : "value"
     	           },
               

  • "boot.properties" - takes either a path to a boot.properties file (relative to the project location) or a list of boot properties and their values.The list must be in the format "string":object, for example:

               "boot.properties" :
     	           {
     	               "property" : true
     	           },
               

• Basic information about the health of the system.

  This information can be accessed over REST at http://localhost:8080/openidm/info/ping. For example:

  $ curl
   --header "X-OpenIDM-Username: openidm-admin"
   --header "X-OpenIDM-Password: openidm-admin"
   --request GET
   "http://localhost:8080/openidm/info/ping"
  
   {"state":"ACTIVE_READY","shortDesc":"OpenIDM ready"}
        

  The information is provided by the script openidm/bin/defaults/script/info/ping.js.

• Information about the current OpenIDM session.

  This information can be accessed over REST at http://localhost:8080/openidm/info/login. For example:

  $ curl
   --header "X-OpenIDM-Username: openidm-admin"
   --header "X-OpenIDM-Password: openidm-admin"
   --request GET
   "http://localhost:8080/openidm/info/login"
  
   {
    "username":"openidm-admin",
    "userid":{
       "id":"openidm-admin",
       "component":"internal/user"
    }
   }      

  The information is provided by the script openidm/bin/defaults/script/info/login.js.

• "infocontext" specifies the relative name of the info endpoint under the info context. The information can be accessed over REST at this endpoint, for example, setting "infocontext" to "mycontext/myendpoint" would make the information accessible over REST at http://localhost:8080/openidm/info/mycontext/myendpoint.

• "type" specifies the type of the information source. Currently, only Javascript is supported, so the type must be "text/javascript".

• "file" specifies the path to the Javascript file, if you do not provide a "source" parameter.

• "source" specifies the actual Javascript, if you have not provided a "file" parameter.

• request - the request details, including the method called and any parameters passed.

• healthinfo - the current health status of the system.

• openidm - access to the JSON resource API.

• Any additional properties that are defined in the configuration file ( openidm/samples/infoservice/conf/info-name.json.)

• Start OpenIDM with the jpda option:

  $ cd /path/to/openidm
  $ ./startup.sh jpda
  ./startup.sh
  Using OPENIDM_HOME:   /Users/lana/openidm
  Using OPENIDM_OPTS:   -Xmx1024m -Djava.compiler=NONE -Xnoagent -Xdebug -Xrunjdwp:transport=dt_socket,address=5005,server=y,suspend=n
  Using LOGGING_CONFIG: -Djava.util.logging.config.file=/Users/lana/openidm/conf/logging.properties
  Listening for transport dt_socket at address: 5005
  Using boot properties at /Users/lana/openidm/conf/boot/boot.properties
  OpenIDM version "2.1.0-SNAPSHOT" (revision: 2144)
  -> OpenIDM ready

  The relevant JPDA options are outlined in the startup script (startup.sh).

• In your IDE, attach a Java debugger to the JVM via socket, on port 5005.