KeyValuePair connector methods

  • Release version: Yokohama
  • Updated January 30, 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 enable you to perform various operations on key-value pairs within automation flows in ServiceNow. These methods can be interconnected with other components to manipulate key-value data efficiently. Before using any method, it must be exposed and configured appropriately within the flow.

    Show full answer Show less

    Key Features

    • Add: Adds a new key-value pair, with an option to ignore duplicates or return an error if a duplicate key exists.
    • Clear: Removes all existing key-value pairs.
    • ContainsKey / ContainsValue: Checks for the existence of a specified key or value, returning a Boolean.
    • Count: Returns the total number of key-value pairs present.
    • Delete: Removes a specified key and its associated value.
    • GetItem / GetItems: Retrieves the value of a single key or multiple keys (which must be preconfigured).
    • GetItemsByIndex: Retrieves key values based on their index positions, configurable via method settings.
    • ParseFromText: Parses a text string into multiple key-value pairs, with options to set separators, clear existing pairs, and reverse key indexes.
    • SetItem / SetItems / SetItemsByIndex: Updates values for single or multiple keys, configurable by name or index. Preconfiguration of keys or indexes is required.
    • ToJSON / ToText: Converts key-value pairs into JSON or text formats. The ToText method can render either only values or key-value pairs based on a Boolean input.

    Practical Use and Configuration

    Many methods require configuration steps such as exposing methods, adding keys or indexes, and setting data types before use. These configurations create appropriate data ports (input or output) that facilitate data flow in automation processes.

    For updating or retrieving multiple keys or indexes, the methods allow you to add multiple keys or indexes via the method settings interface, enabling flexible and dynamic data management.

    To verify updates or outputs after method execution, you can use retrieval methods like GetItemsByIndex.

    Why It Matters

    These connector methods provide robust control over key-value data, which is essential for dynamic automation workflows. They enable ServiceNow customers to manage configuration, data parsing, and transformation tasks seamlessly within flows, improving automation efficiency and data handling precision.

    Expected Outcomes

    • Efficient addition, retrieval, update, and deletion of key-value pairs in automation flows.
    • Ability to parse text into structured key-value data and convert data into JSON or text formats for integration or reporting.
    • Flexible data management through configuration of keys and indexes, supporting complex automation scenarios.
    • Improved error handling and data integrity through options like duplicate key checking and clearing existing data before parsing.

    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