KeyValuePair connector methods

  • Release version: Zurich
  • Updated July 31, 2025
  • 5 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of KeyValuePair Connector Methods

    The KeyValuePair connector methods in ServiceNow enable automation flows to perform diverse operations on key-value pairs. These methods must be exposed and configured before use, allowing you to efficiently manage, query, and manipulate key-value data within your workflows.

    Show full answer Show less

    Key Features

    • Add: Adds a key-value pair with options to ignore duplicates.
    • Clear: Removes all key-value pairs.
    • ContainsKey / ContainsValue: Checks the existence of a specific key or value, returning a Boolean response.
    • Count: Returns the total number of key-value pairs.
    • Delete: Removes a specified key and its value.
    • GetItem: Retrieves the value for a specific key.
    • GetItems: Retrieves values for multiple configured keys, each exposed as a separate data output port.
    • GetItemsByIndex: Retrieves key values based on their configured indexes.
    • ParseFromText: Parses a text string into multiple key-value pairs, with options to clear existing pairs and customize separators.
    • SetItem: Updates the value of a single key.
    • SetItems: Updates values of multiple configured keys via input ports.
    • SetItemsByIndex: Updates values of keys based on their configured indexes.
    • ToJSON / ToText: Converts the key-value pairs into JSON or text format, with an option to output values only.

    Practical Configuration and Use

    Several methods require prior configuration, such as specifying keys or indexes before use. This is done through the method settings, where you add keys or indexes and define their data types. This setup creates corresponding data input or output ports, enabling precise control over which key-value pairs are accessed or updated.

    For methods involving updates or retrievals by key or index, it is recommended to verify changes using GetItemsByIndex to confirm the current state of key-value pairs after operations.

    Why It Matters

    These methods provide a flexible, programmatic way to manage key-value pairs within ServiceNow automation flows. They support complex data handling scenarios such as conditional logic, dynamic updates, and data parsing, enhancing the capability and efficiency of your workflows.

    What You Can Expect

    • Robust handling of key-value data with precise control over additions, deletions, updates, and queries.
    • Improved automation flow design through configurable ports and clear parameter settings.
    • Easy integration of parsed textual data into key-value pairs for dynamic workflow inputs.
    • Output formats in both text and JSON for compatibility with various downstream processes.

    The Keyvalue pair connector methods perform various actions on key value pairs. In an automation flow, the methods are connected with other methods and components. To use the methods, you must first expose them.

    Add

    Adds a keyvalue pair.

    To provide inputs to the parameters, see Configure port properties.

    Table 1. Add method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Key Name of the key. Data in String None Yes
    Value Value of the key. Data in Object None Yes
    IgnoreDuplicates If the value is True, the method ignores a duplicate key. Else, if the value is False, the method returns an error message. Data in Boolean None No

    Clear

    Clears all keyvalue pairs.

    ContainsKey

    Returns True if the specified key exists, else, returns False.

    To provide inputs to the parameters, see Configure port properties.

    Table 2. ContainsKey method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Key Name of the key. Data in String None Yes
    Return Returns True if the specified key exists, else, returns False. Data out Boolean Not applicable Not applicable

    ContainsValue

    Returns True if the specified key value exists, else, returns False.

    To provide inputs to the parameters, see Configure port properties.

    Table 3. ContainsValue method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Value Name of the key value. Data in String None Yes
    Return Returns True if the specified key value exists, else, returns False. Data out Boolean Not applicable Not applicable

    Count

    Returns the total count of keyvalue pairs.

    Table 4. Count method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Return Returns the total count of keyvalue pairs. Data out Integer Not applicable Not applicable

    Delete

    Removes the specified key.

    To provide inputs to the parameters, see Configure port properties.

    Table 5. Delete method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Key Name of the key. Data in String None Yes

    GetItem

    Returns the value of the specified key.

    To provide inputs to the parameters, see Configure port properties.

    Table 6. GetItem method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Key Name of the key. Data in String None Yes
    Return Returns the value of the key. Data out Object Not applicable Not applicable

    GetItems

    Returns the values of multiple keys. You must first configure the keys in the method.

    To configure, do the following steps.
    1. Click the method settings icon (Method settings icon.).
    2. Click the add keys icon (Add keys icon.).
    3. Enter the key name.
    4. Update the key data type from the list.
    5. Repeat the steps to set multiple key names.
    6. Click OK.

      A Data out port is created with each key name you set.

    Table 7. GetItems method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Key Returns the value of the key. Data out Object Not applicable Not applicable

    GetItemsByIndex

    Returns the key values based on their index. You must first configure the indexes in the method.

    To configure, do the following steps.
    1. Click the method settings icon (Method settings icon.).
    2. Click the add indexes icon (Add keys icon.).
    3. Enter the key index.
    4. Update the key data type from the list.
    5. Repeat the steps to set multiple key indexes.
    6. Click OK.

      A Data out port is created with each key index you set.

    Table 8. GetItemsByIndex method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Key index Returns the value of the key. Data out Object Not applicable Not applicable

    ParseFromText

    Parses the specified text into key value pairs. It can create multiple keyvalue pairs.

    To provide inputs to the parameters, see Configure port properties.

    Table 9. ParseFromText method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Text Text comprising the keys and values that the method parses. Data in String None Yes
    ItemSeparator Separator between two keyvalue pairs. Data in String None Yes
    KeyValueSeparator Separator between the key and its value. Data in String None Yes
    ClearBeforeParse If True, clears any existing keyvalue pair before parsing. Data in Boolean None No

    Reverse

    Reverses the key indexes.
    Tip:
    After executing the method, you can see the output by executing the GetItemsByIndex method.

    SetData

    Need information.

    SetItem

    Updates the value of a key.

    To provide inputs to the parameters, see Configure port properties.

    Table 10. SetItem method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Key Name of the key. Data in String None Yes
    Value Updated value of the key. Data in Object None Yes
    Tip:
    Test the updated value by executing the GetItemsByIndex method.

    SetItems

    Updates the values of the specified keys. You must first configure the keys in the method.

    To configure the keys, do the following steps.
    1. Click the method settings icon (Method settings icon.).
    2. Click the add keys icon (Add keys icon.).
    3. Enter the key name.
    4. Update the key data type from the list.
    5. Repeat the steps to set multiple key names.
    6. Click OK.

      A Data in port is created with each key name you set.

    To provide inputs to the parameters, see Configure port properties.

    Table 11. SetItems method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Key Updated value of the key. Data in Object None Yes
    Tip:
    Test the updated value by executing the GetItemsByIndex method.

    SetItemsByIndex

    Updates the values of the keys based on the specified indexes. You must first configure the indexes in the method.

    To configure the indexes, do the following steps.
    1. Click the method settings icon (Method settings icon.).
    2. Click the add indexes icon (Add keys icon.).
    3. Enter the key index.
    4. Update the key data type from the list.
    5. Repeat the steps to set multiple key indexes.
    6. Click OK.

      A Data in port is created with each key index you set.

    Table 12. SetItemsByIndex method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Key Index Index of the key. Data in Object None Yes
    Tip:
    Test the updated value by executing the GetItemsByIndex method.

    ToJSON

    Renders the keyvalue pairs to the JSON format.

    ToText

    Renders the keyvalue pairs to the text format.

    To provide inputs to the parameters, see Configure port properties.

    Table 13. ToText method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    ValuesOnly If True, the method renders only the values of the keys, else, renders the keyvalue pair. Data in Boolean None No
    Return Returns the keyvalue pair to the text format. Data out String Not applicable Not applicable