# mulesoft Object Store Connector - Full Documentation --- product: Object Store Connector version: 1.2 --- # Define Object Stores Examples > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You can define an object store globally in the app so that it can be referenced by name and shared between multiple components, or you can create an object store for one particular component. All object store operations can reference a global object store. For example, for an audit flow that verifies whether certain users are currently authorized, you can reference the object store that you defined in the app: `` ## Defining a Global Object Store Using a global object store is ideal for: - Sharing state across components Because the object store is referenced by name, more than one component can use it. Suppose you have two instances of Salesforce Connector that are configured slightly differently. You can use the same token for both Salesforce Connector instances to avoid the need to reauthenticate. - Sharing state across cluster nodes Use Mule in cluster mode to make information available to every node in the cluster. - Using information in your app’s logic Object Store Connector can manipulate the object store as well as define it. Global object stores are defined as a top-level element with a name that other components can reference. The following example creates an object store named `tokensStore` to store access tokens: ```xml ``` This example is for an in-memory object store and doesn’t provide a recommended configuration for an object store that stores access tokens. - Persistence (`persistent="true"`) Values are stored on disk and can survive a system restart. Setting `persistent` to `false` results in a transient store that stores information only in memory. - Expiration (`expirationInterval`) An expiration thread runs every 30 minutes and discards the elements that exceed their time to live (TTL) or their `maxEntries` limit. - TTL (`entryTtl`) of 1 hour Because access tokens are highly sensitive, you might not want to retain them for more than an hour. Every entry that exceeds the value given in `entryTtl` is automatically deleted. - Size limit (`maxEntries`) Each entry over the limit of 100 entries is discarded when the expiration thread runs. In [Object Store v2](https://docs.mulesoft.com/object-store/), unlimited keys are allowed. ## Configuring Authentication through OAuth This example configures Salesforce Connector authentication through OAuth, and then stores the token in the object store created in the [previous example](#global_os) (`tokensStore`): ```xml ``` ## Defining a Private Object Store Use a private object store when: - The shared state is a security risk. - You don’t want anyone to manipulate the object store from the connector level. For example, to avoid the risk that someone changes the configuration of a **Clear** operation so that it deletes all of your authorization data. The following example defines a private object store that does not have a referable name: ```xml ``` The example provides the idempotent message validator with a custom store that only the validator can access. ## See Also - [Salesforce Help](https://help.salesforce.com) - [Object Store Connector Reference](https://docs.mulesoft.com/object-store-connector/1.2/object-store-connector-reference) --- product: Object Store Connector version: 1.3 is-latest-version: true --- # Define Object Stores Examples > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You can define an object store globally in the app so that it can be referenced by name and shared between multiple components, or you can create an object store for one particular component. All object store operations can reference a global object store. For example, for an audit flow that verifies whether certain users are currently authorized, you can reference the object store that you defined in the app: `` ## Defining a Global Object Store Using a global object store is ideal for: - Sharing state across components Because the object store is referenced by name, more than one component can use it. Suppose you have two instances of Salesforce Connector that are configured slightly differently. You can use the same token for both Salesforce Connector instances to avoid the need to reauthenticate. - Sharing state across cluster nodes Use Mule in cluster mode to make information available to every node in the cluster. - Using information in your app’s logic Object Store Connector can manipulate the object store as well as define it. Global object stores are defined as a top-level element with a name that other components can reference. The following example creates an object store named `tokensStore` to store access tokens: ```xml ``` This example is for an in-memory object store and doesn’t provide a recommended configuration for an object store that stores access tokens. - Persistence (`persistent="true"`) Values are stored on disk and can survive a system restart. Setting `persistent` to `false` results in a transient store that stores information only in memory. - Expiration (`expirationInterval`) An expiration thread runs every 30 minutes and discards the elements that exceed their time to live (TTL) or their `maxEntries` limit. - TTL (`entryTtl`) of 1 hour Because access tokens are highly sensitive, you might not want to retain them for more than an hour. Every entry that exceeds the value given in `entryTtl` is automatically deleted. - Size limit (`maxEntries`) Each entry over the limit of 100 entries is discarded when the expiration thread runs. In [Object Store v2](https://docs.mulesoft.com/object-store/), unlimited keys are allowed. ## Configuring Authentication through OAuth This example configures Salesforce Connector authentication through OAuth, and then stores the token in the object store created in the [previous example](#global_os) (`tokensStore`): ```xml ``` ## Defining a Private Object Store Use a private object store when: - The shared state is a security risk. - You don’t want anyone to manipulate the object store from the connector level. For example, to avoid the risk that someone changes the configuration of a **Clear** operation so that it deletes all of your authorization data. The following example defines a private object store that does not have a referable name: ```xml ``` The example provides the idempotent message validator with a custom store that only the validator can access. ## See Also - [Salesforce Help](https://help.salesforce.com) - [Object Store Connector Reference](https://docs.mulesoft.com/object-store-connector/latest/object-store-connector-reference) --- product: Object Store Connector version: 1.2 keywords: object store, object, store, connector --- # Object Store Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt **Reference:** [Object Store Connector Reference](https://docs.mulesoft.com/object-store-connector/1.2/object-store-connector-reference) Object Store Connector is a Mule component that allows for simple key-value storage. Although it can serve a wide variety of use cases, it is mainly design for: - Storing synchronization information, such as watermarks. - Storing temporal information such as access tokens. - Storing user information. Additionally, Mule Runtime uses Object Stores to support some of its own components, for example: - The Cache module uses an Object Store to maintain all of the cached data. - The OAuth module (and every OAuth enabled connector) uses Object Stores to store the access and refresh tokens. ## Object Store Limitations Object Stores are not a universal solution for data storage. They do not replace a database, and they are not suitable for every use case. Most importantly, they do not support transactional access or modification. For use cases in which [ACID](https://en.wikipedia.org/wiki/ACID) semantics are needed, or for cases where you expect the same key to be updated in parallel, consider another solution. ## Use the Default Object Store By default, each Mule app has an Object Store that is persistent and always available to the app _without any configuration_. Flows can use it to persist and share data. If you want to use the default Object Store, you can specify a `key` for the Object Store without selecting or creating an Object Store reference for the Object Store operation, and without specifying an `objectStore` attribute in the XML element for the Object Store component. You use Anypoint Platform Runtime Manager to deploy Mule apps to CloudHub workers. The key-value pairs (contents) are visible in Runtime Manager if you use persistent Object Store and key-value pairs are stored. ## Use a Custom Object Store Custom Object Stores must specify an `objectStore` attribute. These Object Stores can be configured to behave differently than the default Object Store. For example, you can indicate whether the Object Store is persistent (so that the Object Store data survives a Mule Runtime crash) or transient (where data does not survive a Mule Runtime crash). Here are some common reasons for defining custom Object Stores: - You want to partition your information by storing it in different Object Stores. - You want to use advanced Object Store features such as these: - Transient/Persistent storage. - Specification of a time to live (TTL). - Specification of a max capacity. - You want to keep different components from sharing state by feeding them with different Object Stores. - You want different components to share information by feeding them with the same Object Stores. ## See Also - [Define an Object Store](https://docs.mulesoft.com/object-store-connector/1.2/object-store-to-define-a-new-os) - [Store and Retrieve information from an Object Store](https://docs.mulesoft.com/object-store-connector/1.2/object-store-to-store-and-retrieve) - [Example: Watermark](https://docs.mulesoft.com/object-store-connector/1.2/object-store-to-watermark) - [Object Store Connector in Anypoint Exchange](https://www.mulesoft.com/exchange/org.mule.connectors/mule-objectstore-connector/) --- product: Object Store Connector version: 1.3 is-latest-version: true keywords: object store, object, store, connector --- # Object Store Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt **Reference:** [Object Store Connector Reference](https://docs.mulesoft.com/object-store-connector/latest/object-store-connector-reference) Object Store Connector is a Mule component that allows for simple key-value storage. Although it can serve a wide variety of use cases, it is mainly design for: - Storing synchronization information, such as watermarks. - Storing temporal information such as access tokens. - Storing user information. Additionally, Mule Runtime uses Object Stores to support some of its own components, for example: - The Cache module uses an Object Store to maintain all of the cached data. - The OAuth module (and every OAuth enabled connector) uses Object Stores to store the access and refresh tokens. ## Object Store Limitations Object Stores are not a universal solution for data storage. They do not replace a database, and they are not suitable for every use case. Most importantly, they do not support transactional access or modification. For use cases in which [ACID](https://en.wikipedia.org/wiki/ACID) semantics are needed, or for cases where you expect the same key to be updated in parallel, consider another solution. ## Use the Default Object Store By default, each Mule app has an Object Store that is persistent and always available to the app _without any configuration_. Flows can use it to persist and share data. If you want to use the default Object Store, you can specify a `key` for the Object Store without selecting or creating an Object Store reference for the Object Store operation, and without specifying an `objectStore` attribute in the XML element for the Object Store component. You use Anypoint Platform Runtime Manager to deploy Mule apps to CloudHub workers. The key-value pairs (contents) are visible in Runtime Manager if you use persistent Object Store and key-value pairs are stored. ## Use a Custom Object Store Custom Object Stores must specify an `objectStore` attribute. These Object Stores can be configured to behave differently than the default Object Store. For example, you can indicate whether the Object Store is persistent (so that the Object Store data survives a Mule Runtime crash) or transient (where data does not survive a Mule Runtime crash). Here are some common reasons for defining custom Object Stores: - You want to partition your information by storing it in different Object Stores. - You want to use advanced Object Store features such as these: - Transient/Persistent storage. - Specification of a time to live (TTL). - Specification of a max capacity. - You want to keep different components from sharing state by feeding them with different Object Stores. - You want different components to share information by feeding them with the same Object Stores. ## See Also - [Define an Object Store](https://docs.mulesoft.com/object-store-connector/latest/object-store-to-define-a-new-os) - [Store and Retrieve information from an Object Store](https://docs.mulesoft.com/object-store-connector/latest/object-store-to-store-and-retrieve) - [Example: Watermark](https://docs.mulesoft.com/object-store-connector/latest/object-store-to-watermark) - [Object Store Connector in Anypoint Exchange](https://www.mulesoft.com/exchange/org.mule.connectors/mule-objectstore-connector/) --- product: Object Store Connector version: 1.2 --- # Object Store Connector Examples > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To fully benefit from using Anypoint Connector for Object Store (Object Connector), see the following examples of configuring the connector operations: - [Define Object Stores](https://docs.mulesoft.com/object-store-connector/1.2/object-store-to-define-a-new-os) Define a global or private object store configuration to use in your Mule application. - [Store and Retrieve information in Object Stores](https://docs.mulesoft.com/object-store-connector/1.2/object-store-to-store-and-retrieve) Configure the **Store** and **Retrieve** operations to store and retrieve information in an object store. - [Set up Watermarks with an Object Store](https://docs.mulesoft.com/object-store-connector/1.2/object-store-to-watermark) Configure Object Store Connector parameters to set up watermarking technique in order to store and retrieve the point at which a periodic synchronization should resume the next time it’s executed. ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Salesforce Help](https://help.salesforce.com) --- product: Object Store Connector version: 1.3 is-latest-version: true --- # Object Store Connector Examples > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To fully benefit from using Anypoint Connector for Object Store (Object Connector), see the following examples of configuring the connector operations: - [Define Object Stores](https://docs.mulesoft.com/object-store-connector/latest/object-store-to-define-a-new-os) Define a global or private object store configuration to use in your Mule application. - [Store and Retrieve information in Object Stores](https://docs.mulesoft.com/object-store-connector/latest/object-store-to-store-and-retrieve) Configure the **Store** and **Retrieve** operations to store and retrieve information in an object store. - [Set up Watermarks with an Object Store](https://docs.mulesoft.com/object-store-connector/latest/object-store-to-watermark) Configure Object Store Connector parameters to set up watermarking technique in order to store and retrieve the point at which a periodic synchronization should resume the next time it’s executed. ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Salesforce Help](https://help.salesforce.com) --- product: Object Store Connector version: 1.2 --- # Object Store Connector Reference > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Object Store Connector v1.2.0 Support Category: Select Connector that provides functionality to access and create object store instances. ## Configurations --- ### Config Default configuration #### Parameters
NameTypeDescriptionDefault ValueRequired

Name

String

The name for this configuration. Connectors reference the configuration with this name.

x

Connection

The connection types to provide to this configuration.

x

#### Connection Types ##### Connection A ConnectionProvider that returns the Mule runtime's default ObjectStoreManager. ###### Parameters
NameTypeDescriptionDefault ValueRequired

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn't pass after exhausting the associated reconnection strategy.

## Operations - [Clear](#clear) - [Contains](#contains) - [Remove](#remove) - [Retrieve](#retrieve) - [Retrieve All](#retrieveAll) - [Retrieve All Keys](#retrieveAllKeys) - [Store](#store) ### Clear `` Removes all the contents in the store. #### Parameters
NameTypeDescriptionDefault ValueRequired

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

#### Output

Type

Void

#### Throws - OS:STORE\_NOT\_AVAILABLE ### Contains `` Checks if there is any value associated to the given key. If no value exists for the key, then false is returned. This operation is synchronized at the key level. No other operation can access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes. #### Parameters
NameTypeDescriptionDefault ValueRequired

Key

String

The key of the object to be checked.

x

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

Target Variable

String

The name of a variable to store the operation's output.

Target Value

String

An expression to evaluate against the operation's output and store the expression outcome in the target variable.

#[payload]

#### Output

Type

Boolean

#### Throws - OS:INVALID\_KEY - OS:STORE\_NOT\_AVAILABLE ### Remove `` Removes the value associated to the given key. If no value exists for the key, then an OS:KEY\_NOT\_FOUND error is thrown. This operation is synchronized on the key level. No other operation is able to access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes. #### Parameters
NameTypeDescriptionDefault ValueRequired

Key

String

The key of the object to be removed.

x

Object Store

A reference to the object store to use. If not defined, the runtime's default partition will be used.

#### Output

Type

Void

#### Throws - OS:INVALID\_KEY - OS:STORE\_NOT\_AVAILABLE - OS:KEY\_NOT\_FOUND ### Retrieve `` Retrieves the value stored for the given key. If no value exists for the key, behavior depends on the defaultValue parameter. If the parameter was not provided or was resolved to a null value, then an OS:KEY\_NOT\_FOUND error is thrown. Otherwise, the defaultValue is returned, but that value is not stored. Finally, this operation is synchronized on the key level. No other operation can access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes. #### Parameters
NameTypeDescriptionDefault ValueRequired

Key

String

The key of the value to be retrieved.

x

Default Value

Any

Value to be returned if the key doesn't exist in the store.

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

Target Variable

String

The name of a variable to store the operation's output.

Target Value

String

An expression to evaluate against the operation's output and store the expression outcome in the target variable.

#[payload]

#### Output

Type

Any

#### Throws - OS:INVALID\_KEY - OS:KEY\_NOT\_FOUND - OS:STORE\_NOT\_AVAILABLE ### Retrieve All `` Retrieves all the key value pairs in the object store. #### Parameters
NameTypeDescriptionDefault ValueRequired

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

Target Variable

String

The name of a variable to store the operation's output.

Target Value

String

An expression to evaluate against the operation's output and store the expression outcome in the target variable.

#[payload]

#### Output

Type

Object

#### Throws - OS:STORE\_NOT\_AVAILABLE ### Retrieve All Keys `` Returns a List containing all keys that the object store currently holds values for. #### Parameters
NameTypeDescriptionDefault ValueRequired

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

Target Variable

String

The name of a variable to store the operation's output.

Target Value

String

An expression to evaluate against the operation's output and store the expression outcome in the target variable.

#[payload]

#### Output

Type

Array of String

#### Throws - OS:STORE\_NOT\_AVAILABLE ### Store `` Stores the given value using the given key. This operation can be used either for storing new values or updating existing ones, depending on the value of the failIfPresent. When that parameter is set to `false` (default value), then any pre-existing value associated with that key is overwritten. If the parameter is set to `true`, then an `OS:KEY_ALREADY_EXISTS` error is thrown instead. Another important consideration is regarding null values. It is not allowed to store a null value. However, a common use case is to obtain a value (most likely by evaluating a expression or transformation), testing the value for not null, storing it if present and doing nothing otherwise. The `failOnNullValue` parameter simplifies this use case. Setting it to `false` makes the connector skip null values, which prevents the need to use a `` router to check the condition, while using the default value of `true` makes the connector throw a `NULL_VALUE` error. Finally, this operation is synchronized on the key level. No other operation can access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes. #### Parameters
NameTypeDescriptionDefault ValueRequired

Key

String

The key of the value to be stored.

x

Value

Any

The value to be stored. Should not be null if failOnNullValue is set to true.

#[payload]

Fail If Present

Boolean

Whether to fail or update the pre-existing value if the key already exists on the store.

false

Fail On Null Value

Boolean

Whether to fail or skip the operation if the value is null.

true

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

#### Output

Type

Void

#### Throws - OS:INVALID\_KEY - OS:KEY\_ALREADY\_EXISTS - OS:NULL\_VALUE - OS:STORE\_NOT\_AVAILABLE ## Types ### Reconnection
FieldTypeDescriptionDefault ValueRequired

Fails Deployment

Boolean

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.

Reconnection Strategy

The reconnection strategy to use.

### Reconnect
FieldTypeDescriptionDefault ValueRequired

Frequency

Number

How often in milliseconds to reconnect.

Count

Number

How many reconnection attempts to make.

blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

true

### Reconnect Forever
FieldTypeDescriptionDefault ValueRequired

Frequency

Number

How often in milliseconds to reconnect.

blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

true

### Object Store > [!NOTE] These settings do not apply to [Object Store v2](https://docs.mulesoft.com/object-store/).
FieldTypeDescriptionDefault ValueRequired

Persistent

Boolean

Whether the store is persistent or transient.

true

Max entries

Number

The max number of entries allowed. Exceeding entries are removed when the expiration thread runs. If absent, then the described object store has no size boundaries.

Entry ttl

Number

The entry timeout. If absent, then the described object store has no time boundaries. If entryTtl is set to a value lower than or equal to zero, then the object store never expires.

Entry ttl unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

An entry’s time to live (#entryTtl).

SECONDS

Expiration interval

Number

How frequently the expiration thread should run. The default value is 1 minute.

The expirationInterval field requires that the maxEntries or entryTtl fields also be set. If neither is set, then putting a value in Expiration Interval has no effect and the expiration thread does not run. If expirationInterval is set to a value lower than or equal to zero, then the object store never expires.

1

Expiration interval unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The expiration interval (#expirationInterval).

MINUTES

Configuration Reference

A reference to an os:config element used to declare this object store.

If not provided, the Mule runtime’s default ObjectStoreManager is used. Setting this parameter is necessary only when you want to use a nondefault object store implementation: for example, if you want to have a store that is backed by Redis or JDBC.

### Object Store (Object Store v2) > [!NOTE] These settings apply only to [Object Store v2](https://docs.mulesoft.com/object-store/).
FieldTypeDescriptionDefault ValueRequired

Persistent

Boolean

Whether the store is persistent or transient.

true

Max entries

Not configurable for Object Store v2.

The maximum number of entries is unlimited.

Entry ttl

Number

The entry timeout.

Ignored if the value of expirationInterval is less than or equal to 0.

  • Minimum value: 1 second

  • Maximum value: 30 days

If the field contains:

  • No value

    • Mule versions 4.2.1 and later: Rolling TTL

    • Mule versions earlier than 4.2.1: Static TTL of 30 days by default

  • Less than or equal to 0

    TTL is static and set to the maximum value (2592000 seconds/30 days).

  • Positive number

    TTL is static and set to the specified value (between 1 and 2592000 seconds)

  • Greater than 30 days

    TTL is static and set to the maximum value (2592000 seconds/30 days).

For information about the rolling and static TTL behavior, see Time to Live (TTL).

2592000 seconds (30 days)

Entry ttl unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit for the entry’s time to live (entryTtl).

SECONDS

Expiration interval

Positive number

How frequently the expiration thread runs.

The expirationInterval field requires that the entryTtl field is set; otherwise, it is ignored.

  • If expirationInterval is set to a positive value less than the value of entryTtl, the entry expires based on the entryTtl configuration.

  • If expirationInterval is set to a value less than or equal to zero, entryTtl is ignored.

1 minute

Expiration interval unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The expiration interval (expirationInterval).

MINUTES

Configuration Reference

A reference to an os:config element used to declare this object store.

If not provided, the Mule runtime’s default ObjectStoreManager is used. Setting this parameter is necessary only when you want to use a nondefault object store implementation: for example, if you want to have a store that is backed by Redis or JDBC.

### Object Store Connector
FieldTypeDescriptionDefault ValueRequired

Config Name

String

### Private Object Store > [!NOTE] These settings do not apply to [Object Store v2](https://docs.mulesoft.com/object-store/).
FieldTypeDescriptionDefault ValueRequired

Alias

String

A friendly name to refer to this store in the management user interface. Provide this alias if you would like it to be easier to identify this store. If not provided, Mule auto generates an ID. Use an alias for consistent OAuth token refresh behavior. Without an alias, each Mule app node creates its own partition. This can lead to issues with OAuth token refresh, as each node might try to refresh the token independently.

By providing an alias, you make sure that the Mule app uses the same partition across restarts. As long as the cached key or value is not expired, the caching scope is hit, and the Mule app continues to use the same token. This prevents unnecessary token refreshes and improves application efficiency.

Persistent

Boolean

Whether the store is persistent or transient.

true

Max entries

Number

The maximum number of entries allowed. Exceeding entries are removed when the expiration thread runs. If absent, then the described object store has no size boundaries.

Entry ttl

Number

The entry timeout. If absent, then the described object store has no time boundaries.

Entry ttl unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

An entry’s time to live (#entryTtl).

SECONDS

Expiration interval

Number

How frequently the expiration thread should run. The default value is 1 minute.

The expirationInterval field requires that the maxEntries or entryTtl fields also be set. If neither is set, then putting a value in expirationInterval has no effect and the expiration thread does not run. If expirationInterval is set to a value lower than or equal to zero, then the object store never expires.

1

Expiration interval unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The expiration interval (#expirationInterval).

MINUTES

Configuration Reference

A reference to an os:config element which is used to declare this object store.

If not provided, the Mule runtime’s default ObjectStoreManager is used. Setting this parameter is necessary only when you want to use a nondefault object store implementation: for example, if you want to have a store that is backed by Redis or JDBC.

## See Also - [Salesforce Help](https://help.salesforce.com) --- product: Object Store Connector version: 1.3 is-latest-version: true --- # Object Store Connector Reference > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Object Store Connector v1.3.0 Support Category: Select Connector that provides functionality to access and create object store instances. ## Configurations --- ### Config Default configuration #### Parameters
NameTypeDescriptionDefault ValueRequired

Name

String

The name for this configuration. Connectors reference the configuration with this name.

x

Connection

The connection types to provide to this configuration.

x

Lock Timeout

Number

Timeout for acquiring ObjectStore locks. If not specified, operations wait indefinitely.

Lock Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Time unit for the lock timeout parameter.

SECONDS

#### Connection Types ##### Connection A ConnectionProvider that returns the Mule runtime's default ObjectStoreManager. ###### Parameters
NameTypeDescriptionDefault ValueRequired

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn't pass after exhausting the associated reconnection strategy.

## Operations - [Clear](#clear) - [Contains](#contains) - [Remove](#remove) - [Retrieve](#retrieve) - [Retrieve All](#retrieveAll) - [Retrieve All Keys](#retrieveAllKeys) - [Store](#store) ### Clear `` Removes all the contents in the store. #### Parameters
NameTypeDescriptionDefault ValueRequired

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

#### Output

Type

Void

#### Throws - OS:STORE\_NOT\_AVAILABLE ### Contains `` Checks if there is any value associated to the given key. If no value exists for the key, then false is returned. This operation is synchronized at the key level. No other operation can access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes. #### Parameters
NameTypeDescriptionDefault ValueRequired

Key

String

The key of the object to be checked.

x

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

Target Variable

String

The name of a variable to store the operation's output.

Target Value

String

An expression to evaluate against the operation's output and store the expression outcome in the target variable.

#[payload]

#### Output

Type

Boolean

#### Throws - OS:INVALID\_KEY - OS:STORE\_NOT\_AVAILABLE ### Remove `` Removes the value associated to the given key. If no value exists for the key, then an OS:KEY\_NOT\_FOUND error is thrown. This operation is synchronized on the key level. No other operation is able to access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes. #### Parameters
NameTypeDescriptionDefault ValueRequired

Key

String

The key of the object to be removed.

x

Object Store

A reference to the object store to use. If not defined, the runtime's default partition will be used.

#### Output

Type

Void

#### Throws - OS:INVALID\_KEY - OS:STORE\_NOT\_AVAILABLE - OS:KEY\_NOT\_FOUND ### Retrieve `` Retrieves the value stored for the given key. If no value exists for the key, behavior depends on the defaultValue parameter. If the parameter was not provided or was resolved to a null value, then an OS:KEY\_NOT\_FOUND error is thrown. Otherwise, the defaultValue is returned, but that value is not stored. Finally, this operation is synchronized on the key level. No other operation can access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes. #### Parameters
NameTypeDescriptionDefault ValueRequired

Key

String

The key of the value to be retrieved.

x

Default Value

Any

Value to be returned if the key doesn't exist in the store.

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

Target Variable

String

The name of a variable to store the operation's output.

Target Value

String

An expression to evaluate against the operation's output and store the expression outcome in the target variable.

#[payload]

#### Output

Type

Any

#### Throws - OS:INVALID\_KEY - OS:KEY\_NOT\_FOUND - OS:STORE\_NOT\_AVAILABLE ### Retrieve All `` Retrieves all the key value pairs in the object store. #### Parameters
NameTypeDescriptionDefault ValueRequired

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

Target Variable

String

The name of a variable to store the operation's output.

Target Value

String

An expression to evaluate against the operation's output and store the expression outcome in the target variable.

#[payload]

#### Output

Type

Object

#### Throws - OS:STORE\_NOT\_AVAILABLE ### Retrieve All Keys `` Returns a List containing all keys that the object store currently holds values for. #### Parameters
NameTypeDescriptionDefault ValueRequired

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

Target Variable

String

The name of a variable to store the operation's output.

Target Value

String

An expression to evaluate against the operation's output and store the expression outcome in the target variable.

#[payload]

#### Output

Type

Array of String

#### Throws - OS:STORE\_NOT\_AVAILABLE ### Store `` Stores the given value using the given key. This operation can be used either for storing new values or updating existing ones, depending on the value of the failIfPresent. When that parameter is set to `false` (default value), then any pre-existing value associated with that key is overwritten. If the parameter is set to `true`, then an `OS:KEY_ALREADY_EXISTS` error is thrown instead. Another important consideration is regarding null values. It is not allowed to store a null value. However, a common use case is to obtain a value (most likely by evaluating a expression or transformation), testing the value for not null, storing it if present and doing nothing otherwise. The `failOnNullValue` parameter simplifies this use case. Setting it to `false` makes the connector skip null values, which prevents the need to use a `` router to check the condition, while using the default value of `true` makes the connector throw a `NULL_VALUE` error. Finally, this operation is synchronized on the key level. No other operation can access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes. Running the same application with store operations across multiple nodes without clustering enabled might lead to inconsistent results due to the absence of coordinated locking. #### Parameters
NameTypeDescriptionDefault ValueRequired

Key

String

The key of the value to be stored.

x

Value

Any

The value to be stored. Should not be null if failOnNullValue is set to true.

#[payload]

Fail If Present

Boolean

Whether to fail or update the pre-existing value if the key already exists on the store.

false

Fail On Null Value

Boolean

Whether to fail or skip the operation if the value is null.

true

Object Store

A reference to the object store to use. If not defined, the runtime's default partition is used.

#### Output

Type

Void

#### Throws - OS:INVALID\_KEY - OS:KEY\_ALREADY\_EXISTS - OS:KEY\_NOT\_FOUND - OS:NULL\_VALUE - OS:STORE\_NOT\_AVAILABLE ## Types ### Reconnection
FieldTypeDescriptionDefault ValueRequired

Fails Deployment

Boolean

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.

Reconnection Strategy

The reconnection strategy to use.

### Reconnect
FieldTypeDescriptionDefault ValueRequired

Frequency

Number

How often in milliseconds to reconnect.

Count

Number

How many reconnection attempts to make.

blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

true

### Reconnect Forever
FieldTypeDescriptionDefault ValueRequired

Frequency

Number

How often in milliseconds to reconnect.

blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

true

### Object Store > [!NOTE] These settings do not apply to [Object Store v2](https://docs.mulesoft.com/object-store/).
FieldTypeDescriptionDefault ValueRequired

Persistent

Boolean

Whether the store is persistent or transient.

true

Max entries

Number

The max number of entries allowed. Exceeding entries are removed when the expiration thread runs. If absent, then the described object store has no size boundaries.

Entry ttl

Number

The entry timeout. If absent, then the described object store has no time boundaries. If entryTtl is set to a value lower than or equal to zero, then the object store never expires.

Entry ttl unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

An entry’s time to live (#entryTtl).

SECONDS

Expiration interval

Number

How frequently the expiration thread should run. The default value is 1 minute.

The expirationInterval field requires that the maxEntries or entryTtl fields also be set. If neither is set, then putting a value in Expiration Interval has no effect and the expiration thread does not run. If expirationInterval is set to a value lower than or equal to zero, then the object store never expires.

1

Expiration interval unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The expiration interval (#expirationInterval).

MINUTES

Configuration Reference

A reference to an os:config element used to declare this object store.

If not provided, the Mule runtime’s default ObjectStoreManager is used. Setting this parameter is necessary only when you want to use a nondefault object store implementation: for example, if you want to have a store that is backed by Redis or JDBC.

### Object Store (Object Store v2) > [!NOTE] These settings apply only to [Object Store v2](https://docs.mulesoft.com/object-store/).
FieldTypeDescriptionDefault ValueRequired

Persistent

Boolean

Whether the store is persistent or transient.

true

Max entries

Not configurable for Object Store v2.

The maximum number of entries is unlimited.

Entry ttl

Number

The entry timeout.

Ignored if the value of expirationInterval is less than or equal to 0.

  • Minimum value: 1 second

  • Maximum value: 30 days

Object Store v2 supports two TTL behaviors:

  • Rolling TTL: Each entry access (read or write) extends the expiration timer. This behavior applies only when you omit entryTtl from the configuration (Mule 4.2.1 and later). Entries persist as long as the application accesses them at least once a week.

  • Static TTL: The system fixes the expiration timer at the moment of the write operation. Reads don’t extend this timer. The system evicts the entry at creation_time + entryTtl.

If the field contains:

  • No value

    • Mule versions 4.2.1 and later: Rolling TTL

    • Mule versions earlier than 4.2.1: Static TTL of 30 days by default

  • Less than or equal to 0

    TTL is static and set to the maximum value (2592000 seconds/30 days). Reads do not extend the entry’s lifetime.

  • Positive number

    TTL is static and set to the specified value (between 1 and 2592000 seconds)

  • Greater than 30 days

    TTL is static and set to the maximum value (2592000 seconds/30 days).

Specifying any entryTtl value, including 0, configures the store with static TTL. To use rolling TTL, omit the entryTtl field entirely. Adding entryTtl="0" to a configuration that previously omitted the field changes the eviction behavior from rolling to static (30 days from entry creation, regardless of read activity).

For information about the rolling and static TTL behavior, see Time to Live (TTL).

2592000 seconds (30 days)

Entry ttl unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit for the entry’s time to live (entryTtl).

SECONDS

Expiration interval

Positive number

How frequently the expiration thread runs.

The expirationInterval field requires that the entryTtl field is set; otherwise, it is ignored.

  • If expirationInterval is set to a positive value less than the value of entryTtl, the entry expires based on the entryTtl configuration.

  • If expirationInterval is set to a value less than or equal to zero, entryTtl is ignored.

1 minute

Expiration interval unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The expiration interval (expirationInterval).

MINUTES

Configuration Reference

A reference to an os:config element used to declare this object store.

If not provided, the Mule runtime’s default ObjectStoreManager is used. Setting this parameter is necessary only when you want to use a nondefault object store implementation: for example, if you want to have a store that is backed by Redis or JDBC.

### Object Store Connector
FieldTypeDescriptionDefault ValueRequired

Config Name

String

Lock Timeout

Number

Timeout for acquiring ObjectStore locks. If not specified, operations wait indefinitely.

Lock Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Time unit for the lock timeout parameter.

SECONDS

### Private Object Store > [!NOTE] These settings do not apply to [Object Store v2](https://docs.mulesoft.com/object-store/).
FieldTypeDescriptionDefault ValueRequired

Alias

String

A friendly name to refer to this store in the management user interface. Provide this alias if you would like it to be easier to identify this store. If not provided, Mule auto generates an ID. Use an alias for consistent OAuth token refresh behavior. Without an alias, each Mule app node creates its own partition. This can lead to issues with OAuth token refresh, as each node might try to refresh the token independently.

By providing an alias, you make sure that the Mule app uses the same partition across restarts. As long as the cached key or value is not expired, the caching scope is hit, and the Mule app continues to use the same token. This prevents unnecessary token refreshes and improves application efficiency.

Persistent

Boolean

Whether the store is persistent or transient.

true

Max entries

Number

The maximum number of entries allowed. Exceeding entries are removed when the expiration thread runs. If absent, then the described object store has no size boundaries.

Entry ttl

Number

The entry timeout. If absent, then the described object store has no time boundaries.

Entry ttl unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

An entry’s time to live (#entryTtl).

SECONDS

Expiration interval

Number

How frequently the expiration thread should run. The default value is 1 minute.

The expirationInterval field requires that the maxEntries or entryTtl fields also be set. If neither is set, then putting a value in expirationInterval has no effect and the expiration thread does not run. If expirationInterval is set to a value lower than or equal to zero, then the object store never expires.

1

Expiration interval unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The expiration interval (#expirationInterval).

MINUTES

Configuration Reference

A reference to an os:config element which is used to declare this object store.

If not provided, the Mule runtime’s default ObjectStoreManager is used. Setting this parameter is necessary only when you want to use a nondefault object store implementation: for example, if you want to have a store that is backed by Redis or JDBC.

## See Also - [Salesforce Help](https://help.salesforce.com) --- product: Object Store Connector version: 1.2 --- # Object Store Connector XML and Maven Support > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Although you can manually code a Mule app in XML, it is more efficient to use Anypoint Studio. If you manually code a Mule runtime engine (Mule) app in XML, either from the Anypoint Studio XML editor or from a text editor, you can get access to the connector in your app by adding reference statements to both your XML Mule flow and the Apache Maven `pom.xml` file. When you add the connector in Studio, Studio automatically populates the XML code with the connector’s namespace and schema location. It also adds a dependency to the `pom.xml` file. ## Add a Namespace for the Connector Paste the following code inside the `` tag of the header of your configuration XML: ```xml http://www.mulesoft.org/schema/mule/os http://www.mulesoft.org/schema/mule/os/current/mule-os.xsd ``` This example shows how the namespace statements are placed in the `` XML block: ```xml ``` ## Add a POM File Dependency The Apache Maven `pom.xml` file generated by Anypoint Studio contains dependencies for a Mule app. If you code a Mule app manually, include this XML snippet in your `pom.xml` file to enable access to this connector: ```xml org.mule.connectors mule-objectstore-connector x.x.x mule-plugin ``` Replace `x.x.x` with the version that corresponds to the connector you are using. To obtain the most up-to-date `pom.xml` file information: 1. Go to [Anypoint Exchange](https://www.mulesoft.com/exchange/). 2. In Exchange, click **Login** and supply your Anypoint Platform username and password. 3. In Exchange, search for `object store`. 4. Select the connector. 5. Click **Dependency Snippets** near the upper right of the screen. ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Salesforce Help](https://help.salesforce.com) --- product: Object Store Connector version: 1.3 is-latest-version: true --- # Object Store Connector XML and Maven Support > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Although you can manually code a Mule app in XML, it is more efficient to use Anypoint Studio. If you manually code a Mule runtime engine (Mule) app in XML, either from the Anypoint Studio XML editor or from a text editor, you can get access to the connector in your app by adding reference statements to both your XML Mule flow and the Apache Maven `pom.xml` file. When you add the connector in Studio, Studio automatically populates the XML code with the connector’s namespace and schema location. It also adds a dependency to the `pom.xml` file. ## Add a Namespace for the Connector Paste the following code inside the `` tag of the header of your configuration XML: ```xml http://www.mulesoft.org/schema/mule/os http://www.mulesoft.org/schema/mule/os/current/mule-os.xsd ``` This example shows how the namespace statements are placed in the `` XML block: ```xml ``` ## Add a POM File Dependency The Apache Maven `pom.xml` file generated by Anypoint Studio contains dependencies for a Mule app. If you code a Mule app manually, include this XML snippet in your `pom.xml` file to enable access to this connector: ```xml org.mule.connectors mule-objectstore-connector x.x.x mule-plugin ``` Replace `x.x.x` with the version that corresponds to the connector you are using. To obtain the most up-to-date `pom.xml` file information: 1. Go to [Anypoint Exchange](https://www.mulesoft.com/exchange/). 2. In Exchange, click **Login** and supply your Anypoint Platform username and password. 3. In Exchange, search for `object store`. 4. Select the connector. 5. Click **Dependency Snippets** near the upper right of the screen. ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Salesforce Help](https://help.salesforce.com) --- product: Object Store Connector version: 1.2 keywords: ObjectStore, watermark, synchronization --- # Set Up Watermarks with an Object Store Example > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Watermarking is a technique for storing and retrieving the point at which a periodic synchronization should resume the next time it’s executed. Watermarking is a common use of the object store. ## Background For an explanation of what watermarks are, see [this blog post](https://blogs.mulesoft.com/dev-guides/how-to-tutorials/data-synchronizing-made-easy-with-mule-watermarks/). Limitations of the earlier approach: - Although the `` component allowed setting a custom `ObjectStore`, there was no easy way to create it. This issue is resolved in current implementations. - The `` element required the `` component (replaced by ``) to return an iterable payload, and you had to fully iterate over that payload to obtain the new watermark value. Failure to do so resulted in the value being wrongfully updated or not updated at all. - There was no way to update the watermark with a contingency value if the flow threw an error. How and when the value got updated was not completely clear. When we sat down to figure out how to improve this use case, we realized that the real root of the problem was that in reality the shouldn’t be necessary at all. It’s existence was just a consequence of limitations in other components: - The watermark’s artificial iteration was just a way to compensate for the fact that many data sets could only be iterated once, especially when dealing with binary streams or with connectors doing auto paging. This problem is now fixed in Mule 4 thanks to the repeatable streaming feature - The component’s automatic handling of the `ObjectStore` was just to compensate for UX problems on the old `ObjectStore` support. If the new connector were to provide easier semantics, it wouldn’t be needed at all. ## Mule 4 Example This example shows how to perform the use case described in the blog. ```xml 2017-09-11T00:00:00.000Z " ++ vars.watermark] ]]> #[max(payload map $.LastModifiedDate)] ``` The example is a generic flow that does not require a specific type of trigger. Though you might invoke it from another flow, or you might use a `` to trigger the flow, you can produce watermark semantics without forcing any type of trigger. Then the example defines a custom `ObjectStore` for the watermark, but it is also possible to use the `ObjectStore` that is available implicitly to every app. So you do not need to define a custom `ObjectStore`. The flow starts by retrieving the last watermark value. The Retrieve operation (``) specifies a default value (``) that is available the first time the flow runs, before the first watermark is calculated. This configuration avoids the need for a ` → ` type of pattern. Note that the Retrieve operation stores the watermark value in a target value (`target="watermark"`) to prevent the connector from overriding the message payload. This makes the flow reusable and easier to maintain. You can safely add any kind of operation before the Retrieve operation. The query (``) uses the watermark (`vars.watermark`) to filter the obtained results. The `` points to another flow that does whatever processing is needed, for example, sending data to another system, performing a transformation, or something else. The last step (in ``) is to update the watermark value: - The new watermark value should be the maximum updated timestamp. The example uses `` to provide a DataWeave expression that obtains that value. Note that the repeatable streaming feature prevents the need for you to know the integration logic. Even though the query operation auto-paged, this feature guarantees that you can still iterate the result set again. - `failIfPresent` is set to `false` so that the value will be updated if it is present. Otherwise, the operation would only work the first time and fail if the watermark were already in the object store. - `failOnNullValue` is set to `false`, so if the query comes back empty, the DataWeave expression (which looks for the max value) will return null. Setting it to `false` makes the connector skip null values, which prevents the need to use a router to check the condition, while using the default value of `true` makes the connector throw a `NULL_VALUE` error. --- product: Object Store Connector version: 1.3 is-latest-version: true keywords: ObjectStore, watermark, synchronization --- # Set Up Watermarks with an Object Store Example > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Watermarking is a technique for storing and retrieving the point at which a periodic synchronization should resume the next time it’s executed. Watermarking is a common use of the object store. ## Background For an explanation of what watermarks are, see [this blog post](https://blogs.mulesoft.com/dev-guides/how-to-tutorials/data-synchronizing-made-easy-with-mule-watermarks/). Limitations of the earlier approach: - Although the `` component allowed setting a custom `ObjectStore`, there was no easy way to create it. This issue is resolved in current implementations. - The `` element required the `` component (replaced by ``) to return an iterable payload, and you had to fully iterate over that payload to obtain the new watermark value. Failure to do so resulted in the value being wrongfully updated or not updated at all. - There was no way to update the watermark with a contingency value if the flow threw an error. How and when the value got updated was not completely clear. When we sat down to figure out how to improve this use case, we realized that the real root of the problem was that in reality the shouldn’t be necessary at all. It’s existence was just a consequence of limitations in other components: - The watermark’s artificial iteration was just a way to compensate for the fact that many data sets could only be iterated once, especially when dealing with binary streams or with connectors doing auto paging. This problem is now fixed in Mule 4 thanks to the repeatable streaming feature - The component’s automatic handling of the `ObjectStore` was just to compensate for UX problems on the old `ObjectStore` support. If the new connector were to provide easier semantics, it wouldn’t be needed at all. ## Mule 4 Example This example shows how to perform the use case described in the blog. ```xml 2017-09-11T00:00:00.000Z " ++ vars.watermark] ]]> #[max(payload map $.LastModifiedDate)] ``` The example is a generic flow that does not require a specific type of trigger. Though you might invoke it from another flow, or you might use a `` to trigger the flow, you can produce watermark semantics without forcing any type of trigger. Then the example defines a custom `ObjectStore` for the watermark, but it is also possible to use the `ObjectStore` that is available implicitly to every app. So you do not need to define a custom `ObjectStore`. The flow starts by retrieving the last watermark value. The Retrieve operation (``) specifies a default value (``) that is available the first time the flow runs, before the first watermark is calculated. This configuration avoids the need for a ` → ` type of pattern. Note that the Retrieve operation stores the watermark value in a target value (`target="watermark"`) to prevent the connector from overriding the message payload. This makes the flow reusable and easier to maintain. You can safely add any kind of operation before the Retrieve operation. The query (``) uses the watermark (`vars.watermark`) to filter the obtained results. The `` points to another flow that does whatever processing is needed, for example, sending data to another system, performing a transformation, or something else. The last step (in ``) is to update the watermark value: - The new watermark value should be the maximum updated timestamp. The example uses `` to provide a DataWeave expression that obtains that value. Note that the repeatable streaming feature prevents the need for you to know the integration logic. Even though the query operation auto-paged, this feature guarantees that you can still iterate the result set again. - `failIfPresent` is set to `false` so that the value will be updated if it is present. Otherwise, the operation would only work the first time and fail if the watermark were already in the object store. - `failOnNullValue` is set to `false`, so if the query comes back empty, the DataWeave expression (which looks for the max value) will return null. Setting it to `false` makes the connector skip null values, which prevents the need to use a router to check the condition, while using the default value of `true` makes the connector throw a `NULL_VALUE` error. --- product: Object Store Connector version: 1.2 --- # Store and Retrieve Information in an Object Store Example > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The Object Store connector provides **Store** (``) and **Retrieve** (``) operations. Target variables used with the Object Store connector are described in the [Mule Runtime Target Variables document](https://docs.mulesoft.com/mule-runtime/latest/target-variables). ## Store Information from the Object Store You can use an Object Store to store values like this: ```xml ``` You can use the **Store** operation to store new values or update existing ones, depending on the value of the `failIfPresent` parameter. When this parameter is set to `false` (the default), any pre-existing value associated to that key is overwritten. If the parameter is set to true, then an `OS:KEY_ALREADY_EXISTS` error is thrown instead. Note that it is not possible to store null values. However, it is common to obtain a value by evaluating an expression or transformation: - Testing that the value is not null. - Storing the value if it is present. - Otherwise, doing nothing. The `failOnNullValue` parameter simplifies this use case. By default (`true`), a `OS:NULL_VALUE` error is thrown if a null value is supplied. However, when the parameter is set to `false`, a null value causes this operation to do nothing: No error is raised, and no value is altered. ## Retrieve Information from the Object Store The **Retrieve** operation retrieves the value for a given Object Store key. By default, the retrieved value becomes the message payload. To keep the current payload and store the retrieved value in a variable instead, use the `target` parameter (for example, `target="myVar"` so you can access the value as `vars.myVar`). See [Set Up Watermarks with an Object Store](https://docs.mulesoft.com/object-store-connector/1.2/object-store-to-watermark) for an example that uses `target` to avoid overriding the payload. Use the **Retrieve** operation to read previously stored data in a flow, for example, to resume state, reuse cached values, or pass stored data to the next operation. For all parameters (including `objectStore`, `target`, and `targetValue`), see the [Retrieve](https://docs.mulesoft.com/object-store-connector/1.2/object-store-connector-reference#retrieve) operation in the connector reference. You can use the key to retrieve single values: ```xml ``` The operation returns the stored value (or the default value, if provided). When you don’t use the `target` parameter, that value becomes the new message payload for the rest of the flow. You can use an operation like this one to provide default values when the key is not present in the store: ```xml #[now()] ``` You can have default, complex structures: ```xml ``` Note that the `defaultValue` parameter handles cases in which no value exists for a given key. If you do not provide the parameter and the operation resolves to a null value, an OS:KEY\_NOT\_FOUND error is thrown. Otherwise, the `defaultValue` is returned but not stored. > [!TIP] All Object Store operations are synchronized at the key level. No other operation is able > to access the same key on the same Object Store while the operation is running. If the runtime is > running in cluster mode, this synchronization is also guaranteed across nodes. --- product: Object Store Connector version: 1.3 is-latest-version: true --- # Store and Retrieve Information in an Object Store Example > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The Object Store connector provides **Store** (``) and **Retrieve** (``) operations. Target variables used with the Object Store connector are described in the [Mule Runtime Target Variables document](https://docs.mulesoft.com/mule-runtime/latest/target-variables). ## Store Information from the Object Store You can use an Object Store to store values like this: ```xml ``` You can use the **Store** operation to store new values or update existing ones, depending on the value of the `failIfPresent` parameter. When this parameter is set to `false` (the default), any pre-existing value associated to that key is overwritten. If the parameter is set to true, then an `OS:KEY_ALREADY_EXISTS` error is thrown instead. Note that it is not possible to store null values. However, it is common to obtain a value by evaluating an expression or transformation: - Testing that the value is not null. - Storing the value if it is present. - Otherwise, doing nothing. The `failOnNullValue` parameter simplifies this use case. By default (`true`), a `OS:NULL_VALUE` error is thrown if a null value is supplied. However, when the parameter is set to `false`, a null value causes this operation to do nothing: No error is raised, and no value is altered. ## Retrieve Information from the Object Store The **Retrieve** operation retrieves the value for a given Object Store key. By default, the retrieved value becomes the message payload. To keep the current payload and store the retrieved value in a variable instead, use the `target` parameter (for example, `target="myVar"` so you can access the value as `vars.myVar`). See [Set Up Watermarks with an Object Store](https://docs.mulesoft.com/object-store-connector/latest/object-store-to-watermark) for an example that uses `target` to avoid overriding the payload. Use the **Retrieve** operation to read previously stored data in a flow, for example, to resume state, reuse cached values, or pass stored data to the next operation. For all parameters (including `objectStore`, `target`, and `targetValue`), see the [Retrieve](https://docs.mulesoft.com/object-store-connector/latest/object-store-connector-reference#retrieve) operation in the connector reference. You can use the key to retrieve single values: ```xml ``` The operation returns the stored value (or the default value, if provided). When you don’t use the `target` parameter, that value becomes the new message payload for the rest of the flow. You can use an operation like this one to provide default values when the key is not present in the store: ```xml #[now()] ``` You can have default, complex structures: ```xml ``` Note that the `defaultValue` parameter handles cases in which no value exists for a given key. If you do not provide the parameter and the operation resolves to a null value, an OS:KEY\_NOT\_FOUND error is thrown. Otherwise, the `defaultValue` is returned but not stored. > [!TIP] All Object Store operations are synchronized at the key level. No other operation is able > to access the same key on the same Object Store while the operation is running. If the runtime is > running in cluster mode, this synchronization is also guaranteed across nodes. --- product: Object Store Connector version: 1.2 --- # Troubleshooting Object Store Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To troubleshoot Anypoint Connector for Object Store (Object Store Connector), become familiar with the information about enabling verbose logging and interpreting commonly thrown messages. ## Enable Verbose Logging To get a better understanding of why an application’s interaction fails with Object Store Connector, temporarily enable verbose logging for the connector. Remember to always disable the enhanced verbosity after troubleshooting, because it affects your Mule application performance. To enable verbose logging in the configuration file: 1. Access Anypoint Studio and navigate to the **Package Explorer** view. 2. Open your application’s project name. 3. Open the `src/main/resources` path folder. 4. Open the `log4j2.xml` file inside the folder. 5. Add an `` tag inside the `` tag: ```xml ... ... ``` 6. Save your application changes. 7. Click the project name in **Package Explorer** and then click **Run** > **Run As** > **Mule Application**. ## Understand Common Throws Here is a list of common throw messages and how to interpret them: - OS:KEY\_ALREADY\_EXISTS The Mule app tries to store an object, but the object store already has a value for that key. - OS:STORE\_NOT\_AVAILABLE Cannot access the object store at this time. - OS:INVALID\_KEY The supplied key is invalid. Keys cannot be null nor blank. - OS:KEY\_NOT\_FOUND The object store must access a value, but the supplied key doesn’t exist in that store. - OS:NULL\_VALUE A null value was supplied to the object store. Null values are not supported. ## See Also - [Object Store Connector Reference](https://docs.mulesoft.com/object-store-connector/1.2/object-store-connector-reference) - [Salesforce Help](https://help.salesforce.com) - [Known Issues](https://help.salesforce.com/s/issues) --- product: Object Store Connector version: 1.3 is-latest-version: true --- # Troubleshooting Object Store Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To troubleshoot Anypoint Connector for Object Store (Object Store Connector), become familiar with the information about enabling verbose logging and interpreting commonly thrown messages. ## Enable Verbose Logging To get a better understanding of why an application’s interaction fails with Object Store Connector, temporarily enable verbose logging for the connector. Remember to always disable the enhanced verbosity after troubleshooting, because it affects your Mule application performance. To enable verbose logging in the configuration file: 1. Access Anypoint Studio and navigate to the **Package Explorer** view. 2. Open your application’s project name. 3. Open the `src/main/resources` path folder. 4. Open the `log4j2.xml` file inside the folder. 5. Add an `` tag inside the `` tag: ```xml ... ... ``` 6. Save your application changes. 7. Click the project name in **Package Explorer** and then click **Run** > **Run As** > **Mule Application**. ## Understand Common Throws Here is a list of common throw messages and how to interpret them: - OS:KEY\_ALREADY\_EXISTS The Mule app tries to store an object, but the object store already has a value for that key. - OS:STORE\_NOT\_AVAILABLE Cannot access the object store at this time. - OS:INVALID\_KEY The supplied key is invalid. Keys cannot be null nor blank. - OS:KEY\_NOT\_FOUND The object store must access a value, but the supplied key doesn’t exist in that store. - OS:NULL\_VALUE A null value was supplied to the object store. Null values are not supported. ## See Also - [Object Store Connector Reference](https://docs.mulesoft.com/object-store-connector/latest/object-store-connector-reference) - [Salesforce Help](https://help.salesforce.com) - [Known Issues](https://help.salesforce.com/s/issues)