This documentation supports the 20.02 version of BMC Helix Platform.To view the documentation for the current version, select 20.08 from the Product version menu.

Creating an array node in a document instance

A document instance that represents an array of objects can store multiple inputs from processes and connectors in the array.  In such a document instance, you can insert an array node at a given index or append it at the end. The node value can be a simple data type or a complex object. You can also remove a node from the given index. 

Adding or removing an array element returns an updated document instance. Therefore, you must map this action to some document instance. Ideally, you must map the adding and deleting action to a document instance that you have supplied as input.

Note

Adding an array node is supported only in the Process designer. You cannot add an array node in the Rule designer.

Example

A user wants to update his home address on an online shopping portal. He also wants to add his office address in his profile, on the same portal. He goes to his profile, updates the existing address, and adds his new office address. 

Before you begin

Ensure that you have created a document instance with the following JSON:

Example:

{

      "name":"",

       "empId":"",

       "address": [{"building name": "", "building no": ""}]

}

For more information, see Creating-a-document-instance.

To add an array node

  1. Log in to  BMC Helix Innovation Studio.
  2. To add an array element to a process, from the Workspace tab, navigate to the application for which you want to add an array node. 
  3. In the Process designer, create a new process or navigate to the process in which you want to add the array element.
  4. In Process designer, from the Palette, drag the Add Array Element To Document element onto the canvas.

  5. In the Element Properties pane, enter the properties for the Add Array Element To Document element, as described in the following table:

    Property

    Description

    GENERAL

    Label

    Enter a suitable name for the element.

    Description

    Enter details about the element.

    INPUT MAP

    Document Definition Name

    Select the document definition that you want to use for this process.

    Document Instance

    Document instance is a required input that you can capture from a process variable or other inputs.

    Node Name

    Enter the node name of the array element.

    Value

    Enter the value to be added to the array element.

    Index

    (Optional) Specify the index at which you want to add the value in the array.

    If you enter an invalid input such as a negative value or a value more than the array size, the input is ignored and the value is appended at the end of the array.

    Replace

    (Optional) Select this option if you want to replace the element at the specified index. When replace is selected (True), the new element replaces the old element. When the Replace option is not selected (False), the new element is inserted at the given index.

    MULTI INSTANCE LOOP

    Loop Type

    Select Parallel or Sequential from the list.For information about Multi instance loop, see Creating-process-steps-or-activities.

    GEOMETRY

    Source

    Select the document definition that you want to use for this process.

  6. Click Save. 
Example: Add an array node

In this example, since the index is 2 and replace is false, the new value is added at index 2.

documentInstance = {

"name":"Seth", "empId":"123",

"address": [{"building name": "Home", "building no": "2"}, {"building name": "Office", "building no": "A"}]

}
nodeName = "address"
value ={

"building name": "Sales Office", "building no": "5"

}
index = 2
replace = false

Output:

{

"name":"Seth", "empId":"123",

"address": [{"building name": "Home", "building no": "2"}, {"building name": "Office", "building no": "A"}, {"building name": "Sales Office", "building no": "5"} ]

}




Add-array-node.png

To replace an array node

  1. Log in to BMC Helix Innovation Studio. 
  2. From the Workspace tab, navigate to the application for which you want to create a process to add an array element. 
  3. In the Process designer, create a new process or navigate to the process in which you want to replace the array element.
  4. In Process designer, from the Palette, drag the Add Array Element To Document element onto the canvas.

  5. In the Element Properties pane, enter the properties for the Add Array Element To Document element, as described in the following table:

    Property

    Description

    GENERAL

    Label

    Enter a suitable name for the element.

    Description

    Enter details about the element.

    INPUT MAP

    Document Definition Name

    Select the document definition that you want to use for this process.

    Document Instance

    Document instance is a required input that you can capture from a process variable or other inputs.

    Node Name

    Enter the node name of the array element.

    Value

    Enter the value to be added in the array element.

    Index

    (Optional) Specify the index at which you want to add the value in the array.

    If you enter an invalid input such as a negative value or a value more than the array size, the input is ignored and the value is appended at the end of the array.

    Replace

    Select this option if you want to replace the element at the specified index. The new element replaces the old element.

    MULTI INSTANCE LOOP

    Loop Type

    Select Parallel or Sequential from the list.For information about Multi instance loop, see Creating-process-steps-or-activities.

    GEOMETRY

    Source

    Select the document definition that you want to use for this process.

  6. Click Save. 
Example: Replace an array node

In this example, since index is 0 and replace is true, the element at index 0 is replaced with the new value.

documentInstance = {

      "name":"",

      "empId":"",

      "address": [{"building name": "Home", "building no": "2"}, {"building name": "Office", "building no": "A"}]

}

nodeName = "address"
value ={"building name": "Sales Office", "building no": "5"}
index = 0
replace = true

Output:

{

      "name":"",

      "empId":"",

      "address": [{"building name": "Sales Office", "building no": "5"}, {"building name": "Office", "building no": "A"}]

}



Add-array-node.png









To remove an array node

  1. Log in to BMC Helix Innovation Studio. 
  2. From the Workspace tab, navigate to the application for which you want to create a process to remove an array element. 
  3. In the Process designer, create a new process or navigate to the process from which you want to remove the array element.
  4. In Process designer, from the Palette, drag the Remove Array Element To Document element onto the canvas.

  5. In the Element Properties pane, enter the properties for the Remove Array Element From Document element, as described in the following table:

    Property

    Description

    GENERAL

    Label

    Enter a suitable name for the element.

    Description

    Enter details about the element.

    INPUT MAP

    Document Definition Name

    Select the document definition that you want to use for this process.

    Document Instance

    Document instance is a required input that can be captured from a process variable or other inputs.

    Node Name

    Enter the node name of the array element.

    Index

    Specify the index at which you want to remove the value in the array.

    If you enter an invalid input such as a negative value or value more than the array size, then the input is ignored.

  6. Click Save.
Example: Remove an array node

In this example, since index is 1, the element at index 1 is removed.

documentInstance = {

      "name":"",

      "empId":"",

      "address": [{"building name": "Home", "building no": "2"}, {"building name": "Office", "building no": "A"}]

}

nodeName = "address"
index = 1

Output:

{

      "name":"",

      "empId":"",

      "address": [{"building name": "Home", "building no": "2"}]

}




Remove-array-node.png

Related topics

Defining-a-document-schema

Creating-a-document-instance