{"id":28005,"date":"2017-06-16T14:16:47","date_gmt":"2017-06-16T06:16:47","guid":{"rendered":"http:\/\/localhost\/help\/?page_id=28005"},"modified":"2024-01-17T10:48:00","modified_gmt":"2024-01-17T02:48:00","slug":"ddgetentities","status":"publish","type":"page","link":"https:\/\/oihelp.corporate.ifs.com\/help\/p2-server\/calculations\/ddgetentities\/","title":{"rendered":"DDGetEntities()"},"content":{"rendered":"\n<h2>Format<\/h2>\n<p class=\"intro-text\"><strong>DDGetEntities(Hierarchy,Depth[,StartingEntity][,Templates])<\/strong><\/p>\n<h2>Returns<\/h2>\n<p class=\"intro-text\">Returns the names of all parent or child entities in a hierarchy within a given depth. Optionally, the returned entities can be filtered by specifying a starting entity in the hierarchy and the templates which are expected to be assigned to them.\u00a0<\/p>\n<p class=\"left-bar-yellow\">It is possible to retrieve very large volumes of data through indiscriminate use of this function. Retrieving large amounts of Historian data across a slow network can affect system performance for all users of the system.<\/p>\n<h2>Inputs<\/h2>\n<p class=\"intro-text\"><b>Hierarchy: <\/b>The name of the hierarchy in which to search.<br \/>\n Behaviour: Required<br \/>\n Dimensions: SingleValue<br \/>\n Valid data types: String<\/p>\n<p class=\"intro-text\"><b>Depth<\/b>:<b> <\/b>The maximum number of levels to traverse in the hierarchy. Negative numbers indicate parent entities and positive numbers indicate child entities. E.g. 1 returns all immediate children, 2 returns all children and grandchildren, -1 returns all immediate parents, -2 returns all parents and grandparents.<br \/>\n Behaviour: Required<br \/>\n Dimensions: SingleValue<br \/>\n Valid data types: Integer<\/p>\n<p class=\"intro-text\"><b>StartingEntity<\/b>:<b> <\/b>The name of the entity at which to start the search. If this value is not specified, the function starts the search at the root of the hierarchy. See <a href=\"#Common_Traps\">Common Traps<\/a> below.<br \/>\n Behaviour: Optional (0..1)<br \/>\n Dimensions: SingleValue<br \/>\n Valid data types: String<\/p>\n<p class=\"intro-text\"><b>Templates<\/b>: List of template names that the returned entities must have assigned, within the time range of the fetch request. If an entity does not have one of these templates assigned, it will not appear in the results.<br \/>\n Behaviour: Optional (0..n)<br \/>\n Dimensions: SingleValue<br \/>\n Valid data types: String<\/p>\n<p class=\"left-bar\"><a href=\"https:\/\/oihelp.corporate.ifs.com\/help\/p2-server\/calculations\/calculation-syntax\/#Data_Type\">How to properly format data types<\/a><\/p>\n<h2>Common Traps<\/h2>\n<p class=\"intro-text\">Not specifying a <em>StartingEntity<\/em> means that the function should start at the root of the hierarchy.<\/p>\n<p class=\"intro-text\">If you are searching for entities but omitting the optional <em>Templates<\/em> parameter, you may also omit the <em>StartingEntity<\/em> parameter, or use an empty string. The following syntax examples are both acceptable:<\/p>\n<p class=\"intro-text\"><span class=\"code-fragment\">DDGetEntities(\"myHierarchy\",1)<\/span><br \/>\n <em>or<\/em><br \/>\n <span class=\"code-fragment\">DDGetEntities(\"myHierarchy\",1,\"\")<\/span><\/p>\n<p class=\"intro-text\">If you want to get all of the first level entities with a specific template assigned, the syntax requires an empty string, as follows:<\/p>\n<p class=\"intro-text\"><span class=\"code-fragment\">DDGetEntities(\"myHierarchy\",1,\"\",\"myTemplate\")<\/span><\/p>\n<h2>When to Use<\/h2>\n<p class=\"intro-text\">The result of this function can be passed to <a href=\"https:\/\/oihelp.corporate.ifs.com\/help\/p2-server\/calculations\/ddgetattributes\/\">DDGetAttributes<\/a>() since it returns the entity names with the expected metadata.<\/p>\n<h2>Examples<\/h2>\n<p class=\"intro-text\">Expression: <span class=\"code-fragment\">DDGetEntities(\"myHierarchy\", 2)<\/span><br \/>\n Result: Returns the name of all child and grandchild entities in \"myHierarchy\" starting from the root.<\/p>\n<p class=\"intro-text\">Expression: <span class=\"code-fragment\">DDGetEntities(\"myHierarchy\", 2, \"myEntity\")<\/span><br \/>\n Result: Returns the name of all child and grandchild entities in \"myHierarchy\" starting from \"myEntity\".<\/p>\n<p class=\"intro-text\">Expression: <span class=\"code-fragment\">DDGetEntities(\"myHierarchy\", 2, \"\", \"myTemplate\", \"myTemplate2\")<\/span><br \/>\n Result: Returns the name of all child and grandchild entities in \"myHierarchy\" starting from the root where the entity has \"myTemplate\" or \"myTemplate2\" assigned in the time range of the fetch request.<\/p>\n<p class=\"left-bar\">Tip: If you have access to the sample data, try running the following examples using the <a href=\"https:\/\/oihelp.corporate.ifs.com\/help\/p2-server\/configuring-your-system\/creating-a-calculation\/using-the-calculation-tester\/\">calculation tester<\/a>.\u00a0<\/p>\n<p class=\"intro-text\">Expression: <span class=\"code-fragment\">DDGetEntities(\"P2 Corporate\", 2)<\/span><br \/>\n Result: <span style=\"color: #0000ff;\">P2 Energy Solutions, New South Wales, Queensland, South Australia, Victoria, Western Australia<\/span><\/p>\n<p class=\"intro-text\">Expression: <span class=\"code-fragment\">DDGetEntities(\"P2 Corporate\", 2,\"Kimberley\")<\/span><br \/>\n Result: <span style=\"color: #0000ff;\">Gibb, Meda, Sturt Creek, Billiluna, Tanami, Wolfe Creek, Kimbolton, May, Poultons, Bindarrie, Kalumburu, Nabberu<\/span><\/p>\n<p class=\"intro-text\">Expression: <span class=\"code-fragment\">DDGetEntities(\"P2 Corporate\", 3,\"\",\"Business Unit\")<\/span><br \/>\nResult: <span style=\"color: #0000ff;\">New South Wales, Queensland, South Australia, Victoria, Western Australia<\/span><\/p>\n<p class=\"intro-text\">Expression: <span class=\"code-fragment\">DDGetEntities(\"P2 Corporate\", 3,\"\",\"Business Unit\",\"Region\")<\/span><br \/>\n Result: <span style=\"color: #0000ff;\">New South Wales, Queensland, South Australia, Victoria, Western Australia, GoldFields, Kimberley, Pilbara, Central Victoria, North East Victoria, North West Victoria, Barossa, Flinders Ranges, Murray River, Central West, Far North, North West, Far North Coast, Far West<\/span><\/p>\n<p class=\"intro-text\">Expression: <span class=\"code-fragment\">DDGetEntities(\"P2 Corporate\", -2,\"Kimberley\")<\/span><br \/>\n Result:\u00a0<span style=\"color: #0000ff;\">Western Australia, P2 Energy Solutions<\/span><\/p>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Returns the name of all parent\/child entities in a hierarchy within a given depth.<\/p>\n<p class=\"continue-reading-button\"> <a class=\"continue-reading-link\" href=\"https:\/\/oihelp.corporate.ifs.com\/help\/p2-server\/calculations\/ddgetentities\/\">Read more<i class=\"crycon-right-dir\"><\/i><\/a><\/p>\n","protected":false},"author":1,"featured_media":28050,"parent":3650,"menu_order":87,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":"","_members_access_role":[],"_members_access_error":""},"categories":[9],"tags":[100,282],"class_list":["post-28005","page","type-page","status-publish","has-post-thumbnail","hentry","category-tech-ref","tag-calculations","tag-data-dictionary","Version-4-5-0","Product-srv"],"_links":{"self":[{"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages\/28005","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/comments?post=28005"}],"version-history":[{"count":1,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages\/28005\/revisions"}],"predecessor-version":[{"id":46207,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages\/28005\/revisions\/46207"}],"up":[{"embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages\/3650"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/media\/28050"}],"wp:attachment":[{"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/media?parent=28005"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/categories?post=28005"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/tags?post=28005"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}