{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":4038,"path":"build-workflows/workflow-studio/create-custom-action-array-objects.md","title":"Create a custom action to generate an array of objects from a list of records","bundle":null,"doc_type":null,"release":"australia","body":"\n# Create a custom action to generate an array of objects from a list of records\n\nGenerate an array of objects from a list of User records. Learn how to use a Script step to iterate through a list of records.\n\n## Before you begin\n\nRole required: admin of flow\\_designer\n\n## About this task\n\nUse this example to see demonstrations of these operations and steps.\n\n-   Create an action input for a Department record.\n-   Look up a maximum of three User records for the Department action input.\n-   Configure a Script step to process a list of User records.\n-   Create a script input variable containing the list of User records.\n-   Write script that creates an empty contacts array.\n-   Write script that iterates through the list of User records.\n-   Write script that creates a contact object and maps User record field values to the contact object.\n-   Write script that populates the contacts array with the current contact object.\n-   Create script output variables for the contacts array and child contact object.\n-   Save the contact object as a template.\n-   Output the generated contacts array of objects as a data pill.\n-   Test the action with a sample department.\n\n## Procedure\n\n1.  Create an application to store your work.\n\n    You can use App Engine Studio to plan, create, and deploy applications. For more information about building a custom application, see [Building apps in App Engine Studio](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/aes-app-creation.md).\n\n    For example, create an application called `My Application`.\n\n2.  Navigate to **All** &gt; **Process Automation** &gt; **Workflow Studio**.\n\n3.  On the homepage, select **Actions**.\n\n4.  Select **New** &gt; **Action**\n\n    The system displays the Action Properties dialog.\n\n5.  Enter these sample values.\n\n    |Field|Value|\n    |-----|-----|\n    |Name|Create Contacts Array Of Objects|\n    |Application|Global|\n    |Accessible From|All application scopes|\n\n    **Note:** If you created an application to store and deploy your custom action, use that application instead of global.\n\n6.  Select **Build action**.\n\n    The system displays the Workflow Studio interface.\n\n7.  From the Action Outline, select **Inputs** &gt; **Create Input**\n\n    The system displays a new action input.\n\n8.  Configure the action input with these values.\n\n    \\[Omitted image \"array-objects-config-inputs.png\"\\] Alt text: Create an action input that stores a department record.\n\n    |Field|Value|\n    |-----|-----|\n    |Label|Department|\n    |Type|Reference.Department \\[Reference.cmn\\_department\\]|\n    |Mandatory|True|\n\n9.  From the Action Outline, select **Add a new step**.\n\n    The system displays a list of available steps.\n\n10. Select **Look Up Records**\n\n11. Configure the step with these values.\n\n    \\[Omitted image \"array-objects-config-look-up-records-step.png\"\\] Alt text: Configure the Look Up Records step condition to use the department input variable.\n\n<table id=\"table_cvp_l5p_lhb\"><thead><tr><th>\n\nField\n\n</th><th>\n\nValue\n\n</th></tr></thead><tbody><tr><td>\n\nTable\n\n</td><td>\n\nUser \\[sys\\_user\\]\n\n</td></tr><tr><td>\n\nConditions\n\n</td><td>\n\n\\[Department\\]\\[is\\]\\[action-&gt;Department\\]**Note:** Select the Department data pill from the Input Variables.\n\n</td></tr><tr><td>\n\nOrder by\n\n</td><td>\n\nName\n\n</td></tr><tr><td>\n\nSort Type\n\n</td><td>\n\na to z\n\n</td></tr><tr><td>\n\nMax Results\n\n</td><td>\n\n3\n\n</td></tr></tbody>\n</table>    **Note:** This example limits the **Max Results** setting to three records just for demonstration purposes.\n\n12. From the Action Outline, select **Add a new step**.\n\n    The system displays a list of available steps.\n\n13. Select **Script**.\n\n14. From the Input Variables section, select **Create Variable**.\n\n15. Configure the input variable with these values.\n\n    \\[Omitted image \"array-objects-config-script-step-variable.png\"\\] Alt text: Configure the Script step input variable to use the User records data pill from the Look Up Records step.\n\n<table id=\"table_uby_5zp_lhb\"><thead><tr><th>\n\nField\n\n</th><th>\n\nValue\n\n</th></tr></thead><tbody><tr><td>\n\nName\n\n</td><td>\n\nuserRecords\n\n</td></tr><tr><td>\n\nValue\n\n</td><td>\n\n\\[step-&gt;Look Up Records step-&gt;User Records\\]**Note:** Select the User records data pill from the Look Up Records step.\n\n</td></tr></tbody>\n</table>    **Note:** You can select the **User records** data pill from the data panel or from the Data Pill Picker button.\n\n16. For **Script**, enter the following text.\n\n    ```\n    (function execute(inputs, outputs) {\n      //Create an empty array\n      var contactsArray = [];\n      var i = 0;\n      //Iterate through the list of User records\n      while(inputs.userRecords.next()) {\n        //Create an empty object for each iteration\n        var contactObject = {};\n        //Query User records to assign object values\n        contactObject.first_name = inputs.userRecords.getValue('first_name');\n        contactObject.last_name = inputs.userRecords.getValue('last_name');\n        contactObject.email_address = inputs.userRecords.getValue('email');\n        //Add current object to array\n        contactsArray[i] = contactObject;\n        i += 1;\n      }\n      outputs.contacts = contactsArray;\n    })(inputs, outputs);\n    ```\n\n17. From Output Variables, select **Create Variable**.\n\n18. Configure the output variable with these values.\n\n    \\[Omitted image \"array-objects-config-script-step-output-variables.png\"\\] Alt text: Create an array of objects called contacts. Within the array create an object called contact. Within contact object create three strings variables for first name, last name, and email address.\n\n    |Label|Name|Type|Mandatory|\n    |-----|----|----|---------|\n    |contacts|contacts|Array.Object|True|\n\n19. Expand the contacts Array.Object, and rename the child object to `contact`.\n\n20. From the row for the contact object, select the **Add Child Item** icon \\[Omitted image \"icon-add-child-item.png\"\\].\n\n21. Configure the child item with these values.\n\n    |Label|Name|Type|Mandatory|\n    |-----|----|----|---------|\n    |first name|first\\_name|String|True|\n\n22. From the row for the contact object, select the **Add Child Item** icon \\[Omitted image \"icon-add-child-item.png\"\\].\n\n23. Configure the child item with these values.\n\n    |Label|Name|Type|Mandatory|\n    |-----|----|----|---------|\n    |last name|last\\_name|String|True|\n\n24. From the row for the contact object, select the **Add Child Item** icon \\[Omitted image \"icon-add-child-item.png\"\\].\n\n25. Configure the child item with these values.\n\n    |Label|Name|Type|Mandatory|\n    |-----|----|----|---------|\n    |email address|email\\_address|String|True|\n\n26. From the row for the contact Object, select **Toggle Advanced Inputs**.\n\n27. From the Advanced Options, select **Save As Template**.\n\n    The system displays the Save As Template dialog.\n\n28. For **Enter a Name**, enter `contact`.\n\n    \\[Omitted image \"array-objects-config-script-step-output-variable-template.png\"\\] Alt text: Save the object template with the name contact.\n\n29. Click **Save**.\n\n30. From the Action Outline, select **Outputs** &gt; **Create Output**.\n\n31. Configure the Action Output with these values.\n\n    \\[Omitted image \"array-objects-config-outputs.png\"\\] Alt text: Create an action output called contacts to store an array of objects.\n\n    |Label|Name|Type|Mandatory|\n    |-----|----|----|---------|\n    |contacts|contacts|Array.Object|True|\n\n32. Expand the contacts Array.Object.\n\n33. From the row for the contact Object, select **Toggle Advanced Inputs**.\n\n34. From the Advanced Options, select **Structure** &gt; **Start from Template**.\n\n    The system displays **Template**.\n\n35. For **Template**, select the template you previously saved.\n\n    For example, select **Global: contact**.\n\n36. Select **Exit Edit Mode**.\n\n    The System displays the output fields you created.\n\n37. For **contacts**, select **\\[step-&gt;Script step-&gt;contacts\\]**.\n\n    \\[Omitted image \"array-objects-config-outputs-contacts.png\"\\] Alt text: Configure the action output variable to use the contacts data pill from the Script step.\n\n    **Note:** You can select the Script step **contacts** data pill from the data panel or from the Data Pill Picker button.\n\n38. Click **Save**.\n\n39. Select **Test**.\n\n    The system displays the Test Action dialog.\n\n40. Enter the following test value:\n\n    \\[Omitted image \"array-objects-test-action-department.png\"\\] Alt text: Select the Development department to test your action.\n\n    |Input|Value|\n    |-----|-----|\n    |Department|Development|\n\n41. Select **Run Test**.\n\n    The system runs the action with the test values provided.\n\n42. Select **Your test has finished running. View the Action execution details.**\n\n    The system displays the action execution details.\n\n43. Review the runtime value for the action Output data.\n\n    \\[Omitted image \"array-objects-execution-details-page.png\"\\] Alt text: Execution details page for the test results of your custom action.\n\n    Although the execution details display the output data as a JSON formatted string, the actual output data type is an array of objects. If you need a string version of your output, you can convert the object into a string using the JSON class. For more information about converting a JSON object into a string, see [Scoped JSON - stringify\\(Object jsonObject\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/server-api-reference/JSONScopedAPI.md).\n\n    For this example, the contacts object contains an array of contact objects with first name, last name, and email information for three users in the Development department.\n\n    ```\n    {\n        \"contacts\": \n            \"contact\": [\n                {\n                    \"email_address\": \"allyson.gillispie@example.com\",\n                    \"first_name\": \"Allyson\",\n                    \"last_name\": \"Gillispie\"\n                },\n                {\n                    \"email_address\": \"alva.pennigton@example.com\",\n                    \"first_name\": \"Alva\",\n                    \"last_name\": \"Pennigton\"\n                },\n                {\n                    \"email_address\": \"andrew.och@example.com\",\n                    \"first_name\": \"Andrew\",\n                    \"last_name\": \"Och\"\n                }\n            ]\n        }\n    }\n    \n    ```\n\n\n## Result\n\nYou have a custom action that looks up the Users for a given department and converts those users into an array of contact objects.\n\n## What to do next\n\nCustomize this action to use your own logic.\n\n**Parent Topic:**[Script support for complex data](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/build-workflows/workflow-studio/script-support-complex-data.md)\n\n"}}