PropertiesBasedConfiguration command group (AdminTask)
We can use scripting to customize part of the system configuration using properties files. The WebSphere configuration repository stores many different types of configurations. We can use properties files to customize some of these configurations. We can customize some configurations created by the WebSphere Common Configuration Model (WCCM) or configurations that are deployed as Java EE applications.
The WebSphere Common Configuration Model is configured using the AdminConfig command in scripting.
- AdminConfig.types() lists the types in WCCM
- AdminConfig.attributes("type") lists the attributes for a specific type.
Customizing these types using properties files is often easier than writing a script to make the same changes. In a production environment, Java EE applications are often deployed through the AdminApp command in scripting. For a development environment, the use of a properties file offers an easier to understand syntax when constructing the parameters needed to manage the application. Note that application deployment uses its own set of WCCM types.
Examples of configurations that we cannot directly configure through properties files include:
- SIBus
- Business-level applications
- Key and trust store files
- Web services policy set files
- File based user registry
These configurations are managed through their own AdminTask commands. Note that there is an escape in properties files based configuration to invoke AdminTask commands. But this is just an alternative syntax to calling the commands. The actual configuration is not provided in the properties file.
Use properties files as follows:
- Examine samples documented in Managing specific configuration objects using properties files.
- Copy and paste applicable samples into a text file, edit the samples as needed, and apply the samples to the environment with suitable variable substitutions. There are many samples to cover a wide range of commonly used configurations.
- For a supported WCCM type, we can extract that type from an existing cell as the starting point, edit the extracted file, and apply it back to the existing cell.
For supported WCCM types that are not Cell, Node, Server, or ServerCluster, extract the specific type from an existing cell with the option -options [[PortablePropertiesFile true]] to create a portable file format. Then, edit the properties file and apply it to a different cell with appropriate variable substitutions. We might use this approach to move commonly used configuration subsets such as resource definitions and JVM settings from one environment to another.
Avoid trouble: Use properties files to customize, not replicate or merge environments. Do not extract an entire Cell, Node, Server, or ServerCluster to apply to a different environment. Only a subset of WCCM types are applied, and the extracted information is not merged with the new environment in a meaningful way.gotcha
The following WCCM types are supported:
AccessPointGroup ActivationSpec ActivationSpecTemplateProps ActivitySessionService AdminObject AdminObjectTemplateProps AdminServerAuthentication AdminService AllActivePolicy AllAuthenticatedUserExt AllAuthenticatedUsersInTrustedRealmsExt ApplicationProfileService ApplicationServer Audit AuditEventFactory AuditNotificationMonitor AuditPolicy AuditServiceProvider AuditSpecification AuthenticationMechanism AuthenticationTarget AuthorizationConfig AuthorizationGroup AuthorizationGroupMember AuthorizationProvider AuthorizationTableExt AuthorizationTableImpl BackupCluster BridgeInterface CACertificate CAClient CMPConnectorFactory CacheProvider Cell Certificate Chain Classloader ClusterMember CommonSecureInterop CompensationService ConfigSynchronizationService ConnectionDefTemplateProps ConnectionDefinition ConnectionPool ConnectionTest Connector Cookie CoreGroup CoreGroupAccessPoint CoreGroupBridgeService CoreGroupBridgeSettings CoreGroupServer CryptoHardwareToken CustomAuthMechanism CustomService CustomUserRegistry DCSInboundChannel DPClonableDeviceSettings DPClonableDeviceSettingsVersion DPDevice DPDomain DPDomainVersion DPFirmware DPFirmwareVersion DPManagedSet DPManager DRSConnectionPool DRSPartition DRSSerialization DRSSettings DataPowerMgrInboundChannel DataReplication DataReplicationDomain DataSource DebugService DiagnosticProviderService DigestAuthentication DiskCacheCustomPerformanceSettings DiskCacheEvictionPolicy DistributionQueue DynamicCache EJBCache EJBContainer EJBTimer EndPoint EventGroupProfile EventGroupProfileList EventInfrastructureProvider EventInfrastructureService EventServerProfile EveryoneExt ExtensionMBean ExtensionMBeanProvider ExternalCacheGroup ExternalCacheGroupMember FileTransferService Filter GenericChannelFactory GenericInboundChannel GenericJMSConnectionFactory GenericJMSDestination GenericOutboundChannel HAManagerService HTTPConnector HTTPInboundChannel HTTPOutboundChannel HTTPTransport HTTPTunnelInboundChannel HTTPTunnelOutboundChannel HostAlias I18NService IIOPSecurityProtocol IIOPTransport IconType IdentityAssertionLayer IdentityAssertionQOP IdentityAssertionTypeAssociation InvalidationSchedule J2CActivationSpec J2CAdminObject J2CResourceAdapter J2EEResourcePropertySet JAASAuthData JAASConfiguration JAASConfigurationEntry JAASLoginModule JDBCProvider JFAPFactory JFAPInboundChannel JFAPOutboundChannel JMSProvider JMSTransport JavaProcessDef JavaVirtualMachine KRB Key KeyManager KeyReference KeySet KeySetGroup KeyStore KeyStoreFile LDAPSearchFilter LDAPUserRegistry LTPA Library LibraryRef ListenerPort LocalOSUserRegistry MOfNPolicy MQConnectionFactory MQFAPInboundChannel MQFAPOutboundChannel MQQueue MQQueueConnectionFactory MQTopic MQTopicConnectionFactory MailProvider MailSession ManagementScope MappingModule MemoryCacheEvictionPolicy MessageLayer MessageListener MessageListenerService MessageQOP MimeEntry MonitorPolicy NameServer NoOpPolicy Node NodeGroup ORBInboundChannel ObjectCacheInstance ObjectPool ObjectPoolManagerInfo ObjectPoolProvider ObjectPoolService ObjectRequestBroker OneOfNPolicy OutboundResourceAdapter OutputRedirect PME51ServerExtension PMEServerExtension PMIModule PMIService PMRClusterExtension PeerAccessPoint PeerCoreGroup PluginConfigService PluginProperties PluginServerClusterProperties PortletContainer PreferredServerPolicy PrimaryAdminExt ProcessExecution ProtocolProvider ProxyInboundChannel RASLoggingService RMIConnector RMQChannelFactory RMQOutboundChannel RSAToken Referenceable RepositoryService ResourceAdapter ResourceEnvironmentProvider RoleAssignmentExt SecurityRoleExt ServerEntry ServerExt ServerIndex SIPContainer SIPContainerInboundChannel SIPInboundChannel SIPOutboundChannel SIPProxyInboundChannel SOAPConnector SPNEGO SSLConfig SSLConfigGroup SSLInboundChannel SSLOutboundChannel SWAMAuthentication SchedulerConfiguration SchedulerProvider SchedulerService SecureAssociationService SecureSocketLayer Security SecurityDomain SecurityPermission SecurityProtocolQOP Server ServerCluster ServerIdentity ServiceLog ServletCacheInstance SessionBeanConfig SessionDatabasePersistence SessionManager SingleSignon StartupBeansService StateManageable StatefulSessionBeanConfig StaticPolicy StatisticsProvider StreamRedirect StringNameSpaceBinding SystemMessageServer TAInterceptor TCPFactory TCPInboundChannel TCPOutboundChannel TPVService TaskProvider ThreadPool TimerManagerInfo TimerManagerProvider TraceLog TraceService TransactionService TransportChannelFactory TransportChannelService TransportLayer TransportQOP TrustAssociation TrustManager TrustedAuthenticationRealm TuningParams TunnelAccessPointGroup TunnelPeerAccessPoint TunnelTemplate UDPInboundChannel UDPOutboundChannel URL URLProvider UserExt VariableMap VirtualHost WAS40ConnectionPool WAS40DataSource WASQueue WASQueueConnectionFactory WASTopic WASTopicConnectionFactory WIMUserRegistry WLMCoreGroupBridgePlugin WSNotification WSSchedule WebContainer WebContainerInboundChannel WebModuleConfig WebModuleDeployment WebServer WebserverPluginSettings WeightAdvisor WorkAreaPartition WorkAreaPartitionService WorkAreaService WorkManagerInfo WorkManagerProvider WorkManagerService
applyConfigProperties
Apply properties in a specific properties file to the configuration. The system adds attributes or configuration data to the configuration if a specific properties do not exist. If the properties exist in the configuration, the system sets the new values for the attributes.
Target object: None.
Required parameters
- -propertiesFileName
- Name of the properties file to apply. (String, required)
Optional parameters
- -variablesMapFileName
- Name of the variables map file. This file contains values for variables that the system uses from the properties file. (String, optional)
- -variablesMap
- Values of the variables to use with the properties file. (Properties, optional)
- -reportFileName
- Name of a report file containing the output for the applyConfigProperties command. (String, optional)
- -reportFilterMechanism
- Type of report filter mechanism. Specify All to display all report information. Specify Errors to display error information. Specify Errors_And_Changes to display error and change information. (String, optional)
- -validate
- Whether to validate the properties file before applying the changes. By default, the command validates the properties file. Specify false to disable validation. (Boolean, optional)
- -zipFileName
- Name of the compressed file containing the policy sets we want applied to the cell. (String, optional)
Return value
The command does not return output.
Batch mode example
- Jython string...
AdminTask.applyConfigProperties('-propertiesFileName myPropFile.props -zipFileName myZipFile.zip -validate true')
- Jython list:
AdminTask.applyConfigProperties(['-propertiesFileName', 'myPropFile.props', '-zipFileName', 'myZipFile.zip', '-validate', 'true'])
Interactive mode
- Jython:
AdminTask.applyConfigProperties('-interactive')
createPropertiesFileTemplates
Create template properties files to use to create or delete specific object types. The command stores the template properties file in the properties file specified by the propertiesFileName parameter.
Target object: None.
Required parameters
- -propertiesFileName
- Name of the properties file where the template is stored. (String, required)
- -configType
- Resource type for the template to create. (String, required)
- Specify Server to create a server type properties file template.
- Specify ServerCluster to create a server cluster type properties file template.
- Specify Application to create an application type properties file template.
- Specify AuthorizationGroup to create an authorization group type properties file template.
Optional parameters None
Return value
The command does not return output.
Batch mode example
- Jython string...
AdminTask.createPropertiesFileTemplates('-propertiesFileName serverTemplate.props -configType Server')
- Jython list:
AdminTask.createPropertiesFileTemplates(['-propertiesFileName', 'serverTemplate.props', '-configType', 'Server'])
Interactive mode
- Jython:
AdminTask.createPropertiesFileTemplates('-interactive')
deleteConfigProperties
Delete properties in the configuration as designated in a properties file. The system removes the attributes or configuration data that corresponds to each property in the properties file.
Target object: None.
Required parameters
- -propertiesFileName
- Name of the properties file to delete. (String, required)
Optional parameters
- -variablesMapFileName
- Name of the variables map file. This file contains values for variables that the system uses from the properties file. (String, optional)
- -variablesMap
- Values of the variables to use with the properties file. (Properties, optional)
- -reportFileName
- Name of a report file containing the output for the command. (String, optional)
- -reportFilterMechanism
- Type of report filter mechanism. Specify All to display all report information. Specify Errors to display error information. Specify Errors_And_Changes to display error and change information. (String, optional)
- -validate
- Whether to validate the properties file before applying the changes. By default, the command validates the properties file. Specify false to disable validation. (Boolean, optional)
Return value
The command does not return output.
Batch mode example
- Jython string...
AdminTask.deleteConfigProperties('-propertiesFileName myPropFile.props')
- Jython list:
AdminTask.deleteConfigProperties(['-propertiesFileName', 'myPropFile.props'])
Interactive mode
- Jython:
AdminTask.deleteConfigProperties('-interactive')
extractConfigProperties
Extract configuration data in the form of a properties file. The system exports the most commonly used configuration data and attributes, converts the attributes to properties, and saves the data to a file. We can specify the resource of interest with the target object or the configData parameter. Use the configData parameter to specify a server, node, cluster, policy set, or application instance. If no configuration object is specified, the command extracts the profile configuration data.
For target object, specify the object name of the configuration object. For example...
Node=nodeName:Server=serverName
Parameters...
- -propertiesFileName
- Name of the properties file to extract. (String, required)
Optional parameters
- -configData
- Configuration object instance in the format Node=node1. (String, optional)
- -options
- Specifies additional configuration options, such as GENERATETEMPLATE=true. (Properties, optional)
- -filterMechanism
- Specifies filter information for extracting configuration properties. (String, optional)
- Specify All to extract all configuration properties.
- Specify NO_SUBTYPES to extract the properties of the given object without including the subtypes.
- Specify SELECTED_SUBTYPES to extract specific configuration object subtypes specified with the selectedSubTypes parameter. This can include any subtype for a configuration object or any WCCM type that exists under the object type hierarchy.
- -selectedSubTypes
- Configuration properties to include or exclude when the command extracts the properties. Specify this parameter if set the filterMechanism parameter to NO_SUBTYPES or SELECTED_SUBTYPES. The following strings are examples of subtypes: ApplicationServer, EJBContainer. (String, optional)
Configuration object type Subtypes Extensions AdminService None None Deployment ApplicationName None ApplicationServer TransactionService, DynamicCache, WebContainer, EJBContainer, PortletContainer, SIPContainer, WebserverPluginSettings None AuthorizationGroup None None AuthorizationTableExt None None Cell VirtualHost, DataReplicationDomain, ServerCluster, CoreGroup, NodeGroup, AuthorizationGroup, AuthorizationTableExt, Security, J2CResourceAdapter, JDBCProvider, JMSProvider, MailProvider, URLProvider, EventInfrastructureProvider, ObjectPoolProvider, WorkManagerProvider, TimerManagerProvider, SchedulerProvider, Node, VariableMap None CoreGroup None None CoreGroupBridgeService None None DynamicCache None None EJBContainer None None EventInfrastructureProvider None None EventInfrastructureService None None HAManagerService None None J2CResourceAdapter None None JDBCProvider None None JMSProvider None None JavaVirtualMachine None None Library None None MailProvider None None NameServer None None Node Server, J2CResourceAdapter, JDBCProvider, JMSProvider, MailProvider, URLProvider, EventInfrastructureProvider, ObjectPoolProvider, WorkManagerProvider, TimerManagerProvider, SchedulerProvider, VariableMap The NodeMetadata Extension extracts node Metadata properties. NodeGroup None None ObjectPoolProvider None None ObjectRequestBroker None None PMEServerExtension None None PMIModule None None PMIService None None PortletContainer None None SIPContainer None None SchedulerProvider None None Security JAASAuthData
None Server PMIService, AdminService, CoreGroupBridgeService, TPVService, ObjectRequestBroker, ApplicationServer, NameServer, J2CResourceAdapter, JDBCProvider, JMSProvider, MailProvider, URLProvider, EventInfrastructureProvider, ObjectPoolProvider, WorkManagerProvider, TimerManagerProvider, SchedulerProvider, VariableMap, EventInfrastructureService, PMEServerExtension, Library, HAManagerService, PMIModule, Security The extension lists deployed applications for a specific server. ServerCluster J2CResourceAdapter, JDBCProvider, JMSProvider, MailProvider, URLProvider, ObjectPoolProvider, WorkManagerProvider, TimerManagerProvider, SchedulerProvider, VariableMap The extension lists deployed applications for a specific cluster. TPVService None None TimerManagerProvider None None TransactionService None None URLProvider None None VariableMap None None VirtualHost None None WebContainer None None WebserverPluginSettings None None WorkManagerProvider None None
- -zipFileName
- Name of the compressed file into which to extract policy sets. (String, optional)
Return value
The command returns the name of the properties file that the system creates.
Batch mode example
- Jython string...
AdminTask.extractConfigProperties('-configData Node=myNode -propertiesFileName myNodeProperties.props -zipFileName myZipFile.zip')
- Jython list:
AdminTask.extractConfigProperties(['-configData', 'Node=myNode', '-propertiesFileName', 'myNodeProperties.props', '-zipFileName', 'myZipFile.zip'])
Interactive mode
- Jython string...
AdminTask.extractConfigProperties('-interactive')
(V8502)
Because of the way filtering works, when you extract many objects that are not hierarchically related from a large cell or node scope using SELECTED_SUBTYPE, the system scans parts of the cell or node that might not contain an instance of the targeted object type. We can achieve better performance by iteratively extracting each item and then targeting it explicitly. For example, if the goal is to extract all virtual hosts in a cell (compared to targeting the entire cell for extracting and filtering on the virtual host subtype), performance is improved by querying for all virtual hosts as one operation and then targeting each virtual host in a loop, as shown in the following example:
for vhost in AdminConfig.list( 'VirtualHost' ).splitlines() : name = AdminConfig.showAttribute( vhost, 'name' ) parms = '[-propertiesFileName ' + name + '.properties -configData VirtualHost=' + name + '-options [[PortablePropertiesFile true]] ]' AdminTask.extractConfigProperties(parms)
This example produces a <VIRTUALHOSTNAME>.properties file for each virtualHost in the cell.
validateConfigProperties
Verify properties in the properties file are valid, and can be successfully applied to the new configuration.
Target object: None.
Required parameters
- -propertiesFileName
- Name of the properties file to validate. (String, required)
Optional parameters
- -variablesMapFileName
- Name of the variables map file. This file contains values for variables that the system uses from the properties file. (String, optional)
- -variablesMap
- Values of the variables to use with the properties file. (Properties, optional)
- -reportFileName
- Name of a report file containing the output for the applyConfigProperties command. (String, optional)
- -reportFilterMechanism
- Type of report filter mechanism. Specify All to display all report information. Specify Errors to display error information. Specify Errors_And_Changes to display error and change information. (String, optional)
- -zipFileName
- Name of the compressed file containing the policy sets we want applied to the cell. (String, optional)
Return value
Returns true if the system validates the properties file or policy set .zip file.
Batch mode example
- Jython string...
AdminTask.validateConfigProperties('-propertiesFileName myNodeProperties.props -zipFileName myZipFile.zip -reportFileName report.txt')
- Jython list:
AdminTask.validateConfigProperties(['-propertiesFileName', 'myNodeProperties.props', '-zipFileName', 'myZipFile.zip', '-reportFileName', 'report.txt'])
Interactive mode
- Jython:
AdminTask.validateConfigProperties('-interactive')
Related tasks
Extracting properties filesApply properties files Validate properties files Create server, cluster, application, or authorization group objects using properties files and wsadmin scripting Delete server, cluster, application, or authorization group objects using properties files Create and delete configuration objects using properties files and wsadmin scripting Extracting properties files to troubleshoot the environment Manage environment configurations with properties files