Waiting for engine...
Skip to main content

Working with the Environment Extensions object

Read about the intricacies of using the Environment Extensions object and learn how to perform such actions as overriding extension values, how the object interprets and returns encrypted fields, and working with extensions for multi-install integration packs.

Working with extended values​

The object presents the set of extensible components and fields configured for the processes deployed to a given environment. Most types of extensions such as connection, trading partners, and process properties follow the general structure:

Extension type (e.g. connections, operations)
            Specific component including component ID and name
                Extensible field including field id and value

The types of extensions, such as cross-reference tables that do not follow this structure, are discussed further in this topic. Here is an example of a connection component:

...
<bns:connections>
	<bns:connection id="c80bd1f5-5710-4b05-95a8-436ed746d7bd" name="CRM Data Lake">
		<bns:field id="username" value="admin@mycompany.com” enryptedValueSet="false" usesEncryption="false" componentOverride="false" useDefault="true"/>
		<bns:field id="password" encryptedValueSet="true" usesEncryption="true" componentOverride="false" useDefault="true"/>
		<bns:field id="host" value="" encryptedValueSet="false" usesEncryption="false" componentOverride="false" useDefault="true"/>
		   <bns:CloudManagedSecretConfig usesRemoteSecretsManager="true" secretsManagerType="GCP" secretReference="projects/634801617861/secrets/testQA/versions/6"/> 
	</bns:connection>
...

Here is an example of a listener operation:

...
<bns:operations>
	<bns:operation id="b35783e3-9e85-4b69-91f1-453c31250ca9" name="Generic Listener Operation">
		<bns:field id="options" encryptedValueSet="false" usesEncryption="false"
		componentOverride="false" useDefault="true"/>
		<bns:field id="waitMode" encryptedValueSet="false" usesEncryption="false"
		componentOverride="false" useDefault="true"/>
		<bns:field id="interval" encryptedValueSet="false" usesEncryption="false"
		componentOverride="false" useDefault="true"/>
		<bns:field id="unit" encryptedValueSet="false" usesEncryption="false"
		componentOverride="false" useDefault="true"/>
	</bns:operation>
...

The field-level information indicates whether it overwrites the field and, if so, the current override value. For example, the useDefault attribute suggests this. The attribute is equivalent to the Use Default? checkbox in the Environment Extensions user interface. As a reminder, when you select the Use Default? field (true), it does not overwrite the field and instead uses the value from the component within the process.

Retrieving values​

If you overwrite the field, the GET response shows useDefault=”false” and value contains the override value.

<bns:field id="userName" value="admin@mycompany.com" encryptedValueSet="false" usesEncryption="false" componentOverride="false"/>

If you did not overwrite the field, the GET response shows useDefault=”true” and omits the variable value.

<bns:field id="userName" encryptedValueSet="false" usesEncryption="false" componentOverride="false" useDefault="true"/>

Updating values​

To set an override value for a field when updating environment extensions, set useDefault=”false” and provide a value in the UPDATE request.

<bns:field id="userName" value="new_admin@mycompany.com" useDefault=”false”/>

To override the field with a blank value, set useDefault=”false” and value=”” in the UPDATE request.

<bns:field id="userName" value="" useDefault=”false”/>

To revert the field to use its default value, set useDefault=”true” in the UPDATE request. The variable value is optional.

<bns:field id="userName" useDefault=”true”/>
Important

Retaining current override values for fields other than those you want to modify requires special consideration depending on whether you do a partial or complete update.

  • For partial updates, include only the fields you want to modify in the UPDATE request and omit all other fields and objects.
  • For complete updates, you must provide values for all fields in the UPDATE request, even those you do not want to modify. Fields omitted from the request revert to use their default values. You can copy current override values from a GET request.

Backward compatibility note for useDefault​

Boomi introduced the useDefault attribute in the August 2020 release to more clearly indicate an overridden field or the intent of an update. Previously, this determination was based solely on the presence of the value attribute (or encryptedValueSet for encrypted fields). Boomi encourages you to use the useDefault attribute for this purpose when retrieving and updating extension values. However, Boomi maintains the legacy behavior for backward compatibility.

When updating environment extensions, if you omit useDefault from the UPDATE request but value contains a non-empty value, it overrides the field.

<bns:field id="userName" value="new_admin@mycompany.com"/>

If you omit value or it contains an empty value, the field reverts to use its default value.

<bns:field id="userName"/>

Working with other types of extensions​

The following types of extensions behave differently than those discussed in the Environment Extensions object.

ComponentThings to note
Operation SettingsThe only allowed operations are APIM components and Listener operations for SDK connectors
Cross Reference Table1. To override the table, set overrideValues to true.
2. Replace the entire set of rows with each update.
3. The table’s columns are represented by ref1, ref2, and so on, in the sequence defined within the component.
4. Use the Component Metadata API object to get the latest column labels and other information about the table. <bns:crossReferenceid="1793de67-a62a-458d-884c-b5ab34912ad0"override Values="true" name="xref extension test"> <bns:CrossReferenceRows><bns:row ref1="Human Resources" ref2="HR" ref3="363" /><bns:row ref1="Finance" ref2="FIN" ref3="440"/></bns:CrossReferenceRows></bns:crossReference>
Dynamic Process PropertiesDynamic process properties do not have an explicit useDefault attribute. To override a property, simply provide a value. <bns:property id="MY_PROPERTY" value="new value" />
PGP CertificateThe id is the component ID of the PGP certificate you want to extend.
- Use the Component Metadata API object to get labels and other information about a certificate.<bns:PGPCertificates><bns:PGPCertificateid="ead5dc99-d828-4a3e-9144-d5fea61e42ad" value="85e3c704-22de-4411-8935-3ed9097f29da"/><bns:PGPCertificates>

Working with encrypted fields​

Passwords and other encrypted fields are handled differently for security purposes.

Retrieving values​

If you override the encrypted field, the GET response shows useDefault=”false” and encryptedValueSet=”true”.

<bns:field id="password" encryptedValueSet="true"
        usesEncryption="true" componentOverride="false" useDefault="false"/>

If you did not override the encrypted field, the GET response shows useDefault=”true” and encryptedValueSet=”false”.

<bns:field id="password" encryptedValueSet="false" 
                  usesEncryption="true" componentOverride="false" useDefault="true"/>

Updating values​

Updating override values for encrypted fields behaves the same as non-encrypted fields described previously, with the exception of setting the additional attribute usesEncryption to true.

To override an encrypted field with a new value, set useDefault=”false”, populate value, and set usesEncryption="true" in the UPDATE request. This action is equivalent to turning off the Use Default option in the Environment Extensions user interface.

<bns:field id="password" value=”new_password” 
       usesEncryption="true" useDefault="false"/>

To revert the field to use its default value, set useDefault=”true” in the UPDATE request. The fields value and usesEncryption are optional.

<bns:field id="password" useDefault="true"encryptedValueSet="false"
              usesEncryption="true"/>
Important

Similar to the non-encrypted fields described previously, retaining current override values for encrypted fields other than the fields you want to modify requires special consideration depending on whether you are performing a partial or complete update.

  • For partial updates, include only the encrypted fields you want to modify in the UPDATE request and omit all other fields and objects.
  • For complete updates, you must include all fields in the UPDATE request, even those you do not want to modify. Fields omitted from the request revert to use default values. For encrypted fields, however, you need only to pass the encryptedValueSet=”true” attribute and not the actual encrypted value.

When updating an extension using a partial update but do not want to modify the value, omit the field from the request.

Working with extensions for multi-install integration packs​

Extension values for multi-install integration packs are handled separately from the extension values for deployed processes and single-install integration packs. With multi-install integration packs, you can install the same integration pack to the same environment multiple times and set different extension values for each installation. You identify the collection of extension values for each installation by an extensionGroupId.

  • To retrieve the extensions for a given installation, you must use the QUERY operation and filter for a specific extensionGroupId.

    <QueryConfig xmlns="http://api.platform.boomi.com/">
      <QueryFilter>
        <expression operator="and" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:type="GroupingExpression">
          <nestedExpression operator="EQUALS" property="environmentId"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression">
            <argument>d806057a-9a6e-4b10-85df-c648dcc16abe</argument>
          </nestedExpression>
          <nestedExpression operator="EQUALS" property="extensionGroupId"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression">
            <argument>2545e8cb-3162-4729-8dff-3a8ccfc48933</argument>
          </nestedExpression>
        </expression>
      </QueryFilter>
    </QueryConfig>

  • When updating extensions for a given installation, you must specify the extensionGroupId in the request.

Obtaining the extensionGroupId value​

The extensionGroupid is the ID of the process belonging to a multi-install integration pack, however this is a synthetic ID and does not match the actual process component ID.

Obtaining this ID typically involves a series of API calls. A common sequence to retrieve the extensions for a multi-install integration pack might be as follows:

  1. Query the IntegrationPackEnvironmentAttachment object by environmentId to obtain the integrationPackInstanceId. You can additionally query the IntegrationPackInstance object to identify instances for specific integration packs, if desired.
  2. Query the Process object by integrationPackInstanceId to obtain the id. This id serves as the extensionGroupId in the next call.
  3. Query the EnvironmentExtensions object by environmentId and extensionGroupId.

Working with Custom Properties fields​

You can use custom properties fields to obtain key-value pairs in a connection. Each custom properties field can hold a list of key-value property pairs, and you can optionally encrypt the values using the encrypted attribute. To update extended custom properties fields in a connection using the UPDATE operation, you can use the following structure to build a custom properties field as part of the XML or JSON request.

note

To learn how to implement custom properties fields when building a custom connector, refer to the topic Connector descriptor file.

XML Request for an UPDATE operation​

note
  • When updating custom properties, if you define certain strings as restricted keys in the custom properties field configuration as part of the connector design, the same rules apply here when updated using the API. You cannot use empty and duplicate keys.
  • With customProperties-type fields, if you set the useDefault attribute to true at the field level during an UPDATE operation, it honors the value. The Boomi Enterprise Platform uses the field value, by default, from the component XML saved on the Enterprise platform, even if extended on the Setting environment extensions. Therefore, this field reflects the value when you select the Use connection component value check box in the Environment Extensions dialog. Similarly, if you set the useDefault attribute to false during an UPDATE operation, it uses the extended value.
  • If you make a partial UPDATE request, you need to send all existing key-value pairs, in addition to any new key-value pairs or changes to existing key-value pairs. It is necessary because field updates are done at the field-level and not at the key-value pair level.
  • For GCP secret manager, the secret reference must be in the following format: projects/${project-id}/secrets/${secret-id}/versions/${version-id}. If the passed secret reference is valid, a success message is displayed. For an invalid secret reference, an error message “Invalid Secret Reference Value” is displayed. The user must have ADC set up on the system where the Atom runtime is installed and running. For more information on GCP, refer to Set up ADC for a local development environment topic.

<bns:connection name="Local MySql" id="9ba5dfab-8781-4e6a-b908-0c7a7797d17a">
<bns:field componentOverride="false" usesEncryption="false" encryptedValueSet="false" id="driverId" useDefault="true">
     <bns:customProperties>
   	<bns:properties key="encryptedKey" value="encryptedValue" encrypted="true"/>
   	<bns:properties key="plainTextKey" value="plainTextValue" encrypted="false"/>
     </bns:customProperties>
	   <bns:CloudManagedSecretConfig usesRemoteSecretsManager="true" secretsManagerType="GCP" secretReference="projects/634801617861/secrets/testQA/versions/6"/> 
</bns:field>
</bns:connection>

JSON Request​

"field" : [
           	{
              	"@type" : "Field",
              	"customProperties": {
                        	"@type": "customProperties",
                        	"properties": [
                            	{
                                	"@type": "PropertyPair",
                                	"key": "plaintTextKey",
                                	"value": "plainTextValue",
                                	"encrypted": false
                            	},
                            	{
                                	"@type": "PropertyPair",
                                	"key": "encryptedKey",
                                	"value":"encryptedValue",
                                	"encrypted": true
                            	}
                        	]
                    	},
                            	 
              	"id" : "port",
              	"value" : "9090",
              	"encryptedValueSet" : false,
              	"usesEncryption" : false,
              	"componentOverride" : false,
              	"useDefault" : false
           	},
]

Sample XML Response for GET or QUERY​

note

When retrieving extended custom properties using the GET and QUERY operations, the structure of the response for custom properties remains the same as that of the request, with one exception. For security reasons, the Enterprise platform omits values for encrypted property pairs (indicated by the encrypted=true attribute).


<bns:connections>
<bns:connection name="Local MySql" id="9ba5dfab-8781-4e6a-b908-0c7a7797d17a">
     <bns:field componentOverride="false" usesEncryption="false" encryptedValueSet="false" id="exhaustedAction" useDefault="true"
          <bns:customProperties>
   	     <bns:properties key="encryptedKey" encrypted="true"/>
   	     <bns:properties key="plainTextKey" value="plainTextValue" encrypted="false"/>
          </bns:customProperties>
     </bns:field>
     <bns:field componentOverride="false" usesEncryption="false" encryptedValueSet="false" id="driverId" useDefault="true"/>
	   <bns:CloudManagedSecretConfig usesRemoteSecretsManager="true" secretsManagerType="GCP" secretReference="projects/634801617861/secrets/testQA/versions/6"/> 
</bns:connection>
On this Page