WorkdirOverride configuration

Use the WorkdirOverride configuration to provide a list of overrides to apply to one or more co-related BAR files in the work directory of your integration runtime before the runtime starts.

Summary of key details

File name or type
.txt file
Does the file contain secrets?
Yes
Location of imported or extracted data
/home/aceuser/initial-config/workdir_overrides
Maximum number of WorkdirOverride configurations allowed per integration runtime
Multiple

The WorkdirOverride file

The WorkdirOverride configuration requires a .txt file that lists the overrides that you want to apply to one or more BAR files that you're deploying. The specified overrides are used to run ibmint apply overrides commands against the work directory of the integration runtime. The override values in the .txt file replace configurable values in the BAR deployment descriptor (typically broker.xml). For more information, see ibmint apply overrides command in the IBM® App Connect Enterprise documentation.

To create a WorkdirOverride file, complete the following steps.
  1. Create a text file (filename.txt) to contain the overrides to apply.
  2. Add a line to the file for each override that you want to apply. You can add multiple override entries for multiple BAR files.
    Tip: To view the properties that you want to override for any Toolkit or Designer BAR file, extract the contents of the compressed FlowName.appzip or flow_name.appzip file in the BAR file. The properties are specified in the broker.xml file within the META-INF subdirectory, and are shown in the following format:

    <ConfigurableProperty uri="xxxx"/>

    Location of the broker.xml file within a sample BAR file
    Each override that you specify must conform to one of the following syntaxes.
    • FlowName#NodeName.PropertyName=NewPropertyValue (or FlowName#PropertyName=NewPropertyValue for message flow properties)
      • FlowName is the name of the message flow without either the .msgflow or .cmf extension (for example, in_out_simple_mq). If the message flow is within a subdirectory, the subdirectory is included as a subdir. prefix in FlowName (for example, gen.CustomerDatabaseV1 or gen.Customer_API).
      • NodeName is the optional name of the node whose property is overridden (for example, InputNode or HTTP Input).
      • PropertyName is the name of the property to be overridden (for example, queueName or URLSpecifier).
      • NewPropertyValue is the value to assign to that property (for example, PRODUCTION_QUEUE_NAME or /Customer_API/*).
    • OldPropertyValue=NewPropertyValue

      This syntax does a global search and replace on the property value OldPropertyValue. The syntax overrides the value of OldPropertyValue in the deployment descriptor with NewPropertyValue.

    • FlowName#NodeName.PropertyName (or FlowName#PropertyName for message flow properties)

      This syntax removes any override that is applied to the property of the supplied name.

    The following example shows the contents of a broker.xml file that was extracted from the CustomerDatabaseV1.appzip archive within a BAR file named CustomerDatabaseV1.bar.
    <?xml version="1.0" encoding="UTF-8"?><Broker>
<CompiledApplication>
<ConfigurableProperty uri="startMode"/>
<ConfigurableProperty uri="javaIsolation"/>
</CompiledApplication>
<CompiledMessageFlow name="getAllCustomers" type="subflow">
<ConfigurableProperty uri="getAllCustomers#Compute.dataSource"/>
<ConfigurableProperty uri="getAllCustomers#Compute.connectDatasourceBeforeFlowStarts"/>
<ConfigurableProperty uri="getAllCustomers#Compute.validateMaster"/>
</CompiledMessageFlow>
<CompiledMessageFlow name="addCustomer" type="subflow"/>
<CompiledMessageFlow name="getCustomer" type="subflow"/>
<CompiledMessageFlow name="deleteCustomer" type="subflow">
<ConfigurableProperty uri="deleteCustomer#Java Compute.javaClassLoader"/>
<ConfigurableProperty uri="deleteCustomer#Java Compute.validateMaster"/>
</CompiledMessageFlow>
<CompiledMessageFlow name="gen.CustomerDatabaseV1">
<ConfigurableProperty uri="gen.CustomerDatabaseV1#additionalInstances"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#notificationThresholdMsgsPerSec"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#maximumRateMsgsPerSec"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#processingTimeoutSec"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#processingTimeoutAction"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#wlmPolicy"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#commitCount"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#commitInterval"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#coordinatedTransaction"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#consumerPolicySet"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#providerPolicySet"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#consumerPolicySetBindings"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#providerPolicySetBindings"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#securityProfileName"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#monitoringProfile"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#startMode"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#startInstancesWhenFlowStarts"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#HTTP Input.URLSpecifier"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#HTTP Input.useHTTPS"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#HTTP Input.decompressInputMessage"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#HTTP Input.timeoutForClient"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#HTTP Input.faultFormat"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#HTTP Input.validateMaster"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#HTTP Input.securityProfileName"/>
<ConfigurableProperty uri="gen.CustomerDatabaseV1#HTTP Reply.validateMaster"/>
</CompiledMessageFlow>
<CompiledMessageFlow name="updateCustomer" type="subflow"/>
</Broker>
    The following example shows the contents of a .txt file that overrides three properties in the broker.xml file when the CustomerDatabaseV1.bar file is extracted to the work directory of the integration runtime. 
    gen.CustomerDatabaseV1#additionalInstances=2
gen.CustomerDatabaseV1#HTTP Input.URLSpecifier=/production/v1*
gen.CustomerDatabaseV1#HTTP Input.faultFormat=HTML
  3. Save and close the filename.txt file.

To configure your integration to use overrides, create a WorkdirOverride configuration on the Configurations tab of the Manage page. For more information, see Providing credentials and secrets in configurations.

You can then import the overrides .txt file into the WorkdirOverride editor, or paste in the contents.
WorkdirOverride text editor with pasted contents
Tip: For security reasons, the .txt content that you add is available only as REDACTED content after you create the configuration. If you need to update this content later, make sure that you retain a copy of the original file that you used to create this configuration so that you can update it. The update replaces the original content with the edited content.
When you deploy one or more BAR files that use a WorkdirOverride configuration, the following command applies the overrides to the relevant BAR files in the work directory before the integration runtime starts.
ibmint apply overrides /home/aceuser/initial-config/workdir-overrides/filename.txt --work-directory /home/aceuser/ace-server
The logs indicate that the overrides are applied, as shown in the following example.
2021-05-18T19:37:16.850Z Applying workdir overrides to the integration server
BIP1138I: Applying overrides using runtime ibmint apply overrides...
BIP1140I: Overriding property gen.CustomerDatabaseV1#HTTP Input.URLSpecifier with '/production/v1*' in '/home/aceuser/ace-server/run/CustomerDatabaseV1/META-INF/broker.xml' ...
BIP8071I: Successful command completion.
2021-05-18T19:37:17.836Z Workdir overrides applied to the integration server complete