Update documentation on sub-org vs shared org recommendations - INPLATFORM-156

docs/images/IICS-Organization-hierarchy.svg

+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:lucid="lucid" width="560" height="580"><g transform="translate(-380 -60)" lucid:page-tab-id="0_0"><path d="M0 0h1760v1360H0z" fill="#fff"/><path d="M400 86c0-3.3 2.7-6 6-6h188c3.3 0 6 2.7 6 6v168c0 3.3-2.7 6-6 6H406c-3.3 0-6-2.7-6-6z" stroke="#5e5e5e" stroke-width="3" fill="#fff"/><use xlink:href="#a" transform="matrix(1,0,0,1,405,85) translate(31.172839506172828 60.27777777777778)"/><use xlink:href="#b" transform="matrix(1,0,0,1,405,85) translate(43.20987654320988 86.94444444444446)"/><use xlink:href="#c" transform="matrix(1,0,0,1,405,85) translate(114.75308641975309 86.94444444444446)"/><use xlink:href="#d" transform="matrix(1,0,0,1,405,85) translate(50.64814814814815 113.61111111111111)"/><use xlink:href="#e" transform="matrix(1,0,0,1,405,85) translate(99.96913580246914 113.61111111111111)"/><path d="M420 466c0-3.3 2.7-6 6-6h148c3.3 0 6 2.7 6 6v148c0 3.3-2.7 6-6 6H426c-3.3 0-6-2.7-6-6z" stroke="#5e5e5e" stroke-width="3" fill="#fff"/><use xlink:href="#a" transform="matrix(1,0,0,1,425,465) translate(11.172839506172828 50.59027777777778)"/><use xlink:href="#f" transform="matrix(1,0,0,1,425,465) translate(28.734567901234563 77.25694444444446)"/><use xlink:href="#g" transform="matrix(1,0,0,1,425,465) translate(70.70987654320987 77.25694444444446)"/><use xlink:href="#h" transform="matrix(1,0,0,1,425,465) translate(108.91975308641975 77.25694444444446)"/><use xlink:href="#i" transform="matrix(1,0,0,1,425,465) translate(5.987654320987673 103.92361111111111)"/><use xlink:href="#j" transform="matrix(1,0,0,1,425,465) translate(100.86419753086419 103.92361111111111)"/><path d="M500 262.5V440" stroke="#5e5e5e" stroke-width="2" fill="none"/><path d="M501 262.53h-2v-1.03h2z" fill="#5e5e5e"/><path d="M500 455.26L495.36 441h9.28z" stroke="#5e5e5e" stroke-width="2" fill="#5e5e5e"/><path d="M720 86c0-3.3 2.7-6 6-6h188c3.3 0 6 2.7 6 6v168c0 3.3-2.7 6-6 6H726c-3.3 0-6-2.7-6-6z" stroke="#5e5e5e" stroke-width="3" fill="#fff"/><g><use xlink:href="#a" transform="matrix(1,0,0,1,725,85) translate(31.172839506172828 60.27777777777778)"/><use xlink:href="#b" transform="matrix(1,0,0,1,725,85) translate(43.20987654320988 86.94444444444446)"/><use xlink:href="#c" transform="matrix(1,0,0,1,725,85) translate(114.75308641975309 86.94444444444446)"/><use xlink:href="#k" transform="matrix(1,0,0,1,725,85) translate(16.759259259259252 113.61111111111111)"/><use xlink:href="#e" transform="matrix(1,0,0,1,725,85) translate(133.85802469135803 113.61111111111111)"/></g><path d="M740 466c0-3.3 2.7-6 6-6h148c3.3 0 6 2.7 6 6v148c0 3.3-2.7 6-6 6H746c-3.3 0-6-2.7-6-6z" stroke="#5e5e5e" stroke-width="3" fill="#fff"/><g><use xlink:href="#a" transform="matrix(1,0,0,1,745,465) translate(11.172839506172828 50.59027777777778)"/><use xlink:href="#f" transform="matrix(1,0,0,1,745,465) translate(28.734567901234563 77.25694444444446)"/><use xlink:href="#g" transform="matrix(1,0,0,1,745,465) translate(70.70987654320987 77.25694444444446)"/><use xlink:href="#h" transform="matrix(1,0,0,1,745,465) translate(108.91975308641975 77.25694444444446)"/><use xlink:href="#i" transform="matrix(1,0,0,1,745,465) translate(1.697530864197546 103.92361111111111)"/><use xlink:href="#l" transform="matrix(1,0,0,1,745,465) translate(96.57407407407406 103.92361111111111)"/></g><path d="M820 262.5V440" stroke="#5e5e5e" stroke-width="2" fill="none"/><path d="M821 262.53h-2v-1.03h2z" fill="#5e5e5e"/><path d="M820 455.26L815.36 441h9.28z" stroke="#5e5e5e" stroke-width="2" fill="#5e5e5e"/><defs><path fill="#333" d="M232-93c-1 65-40 97-104 97C67 4 28-28 28-90v-158h33c8 89-33 224 67 224 102 0 64-133 71-224h33v155" id="m"/><path fill="#333" d="M266 0h-40l-56-210L115 0H75L2-248h35L96-30l15-64 43-154h32l59 218 59-218h35" id="n"/><path fill="#333" d="M16-82v-28h88v28H16" id="o"/><path fill="#333" d="M240 0l2-218c-23 76-54 145-80 218h-23L58-218 59 0H30v-248h44l77 211c21-75 51-140 76-211h43V0h-30" id="p"/><path fill="#333" d="M141-36C126-15 110 5 73 4 37 3 15-17 15-53c-1-64 63-63 125-63 3-35-9-54-41-54-24 1-41 7-42 31l-33-3c5-37 33-52 76-52 45 0 72 20 72 64v82c-1 20 7 32 28 27v20c-31 9-61-2-59-35zM48-53c0 20 12 33 32 33 41-3 63-29 60-74-43 2-92-5-92 41" id="q"/><path fill="#333" d="M85-194c31 0 48 13 60 33l-1-100h32l1 261h-30c-2-10 0-23-3-31C134-8 116 4 85 4 32 4 16-35 15-94c0-66 23-100 70-100zm9 24c-40 0-46 34-46 75 0 40 6 74 45 74 42 0 51-32 51-76 0-42-9-74-50-73" id="r"/><path fill="#333" d="M24-231v-30h32v30H24zM24 0v-190h32V0H24" id="s"/><path fill="#333" d="M135-143c-3-34-86-38-87 0 15 53 115 12 119 90S17 21 10-45l28-5c4 36 97 45 98 0-10-56-113-15-118-90-4-57 82-63 122-42 12 7 21 19 24 35" id="t"/><path fill="#333" d="M100-194c62-1 85 37 85 99 1 63-27 99-86 99S16-35 15-95c0-66 28-99 85-99zM99-20c44 1 53-31 53-75 0-43-8-75-51-75s-53 32-53 75 10 74 51 75" id="u"/><path fill="#333" d="M117-194c89-4 53 116 60 194h-32v-121c0-31-8-49-39-48C34-167 62-67 57 0H25l-1-190h30c1 10-1 24 2 32 11-22 29-35 61-36" id="v"/><g id="a"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#m"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,15.987654320987653,0)" xlink:href="#n"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,36.48148148148148,0)" xlink:href="#o"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,43.82716049382716,0)" xlink:href="#p"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,62.28395061728395,0)" xlink:href="#q"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,74.62962962962963,0)" xlink:href="#r"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,86.97530864197532,0)" xlink:href="#s"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,91.85185185185186,0)" xlink:href="#t"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,102.96296296296298,0)" xlink:href="#u"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,115.30864197530866,0)" xlink:href="#v"/></g><path fill="#333" d="M30-248c87 1 191-15 191 75 0 78-77 80-158 76V0H30v-248zm33 125c57 0 124 11 124-50 0-59-68-47-124-48v98" id="w"/><path fill="#333" d="M114-163C36-179 61-72 57 0H25l-1-190h30c1 12-1 29 2 39 6-27 23-49 58-41v29" id="x"/><path fill="#333" d="M100-194c63 0 86 42 84 106H49c0 40 14 67 53 68 26 1 43-12 49-29l28 8c-11 28-37 45-77 45C44 4 14-33 15-96c1-61 26-98 85-98zm52 81c6-60-76-77-97-28-3 7-6 17-6 28h103" id="y"/><path fill="#333" d="M59-47c-2 24 18 29 38 22v24C64 9 27 4 27-40v-127H5v-23h24l9-43h21v43h35v23H59v120" id="z"/><g id="b"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#w"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,14.814814814814813,0)" xlink:href="#q"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,27.160493827160494,0)" xlink:href="#x"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,34.50617283950617,0)" xlink:href="#y"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,46.85185185185185,0)" xlink:href="#v"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,59.197530864197525,0)" xlink:href="#z"/></g><path fill="#333" d="M177-190C167-65 218 103 67 71c-23-6-38-20-44-43l32-5c15 47 100 32 89-28v-30C133-14 115 1 83 1 29 1 15-40 15-95c0-56 16-97 71-98 29-1 48 16 59 35 1-10 0-23 2-32h30zM94-22c36 0 50-32 50-73 0-42-14-75-50-75-39 0-46 34-46 75s6 73 46 73" id="A"/><g id="c"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#u"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,12.345679012345679,0)" xlink:href="#x"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,19.691358024691358,0)" xlink:href="#A"/></g><path fill="#333" d="M87 75C49 33 22-17 22-94c0-76 28-126 65-167h31c-38 41-64 92-64 168S80 34 118 75H87" id="B"/><g id="d"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#B"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,7.345679012345679,0)" xlink:href="#z"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,13.518518518518519,0)" xlink:href="#y"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,25.864197530864196,0)" xlink:href="#t"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,36.9753086419753,0)" xlink:href="#z"/></g><path fill="#333" d="M33-261c38 41 65 92 65 168S71 34 33 75H2C39 34 66-17 66-93S39-220 2-261h31" id="C"/><g id="e"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#u"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,12.345679012345679,0)" xlink:href="#x"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,19.691358024691358,0)" xlink:href="#A"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,32.03703703703704,0)" xlink:href="#C"/></g><path fill="#333" d="M84 4C-5 8 30-112 23-190h32v120c0 31 7 50 39 49 72-2 45-101 50-169h31l1 190h-30c-1-10 1-25-2-33-11 22-28 36-60 37" id="D"/><path fill="#333" d="M115-194c53 0 69 39 70 98 0 66-23 100-70 100C84 3 66-7 56-30L54 0H23l1-261h32v101c10-23 28-34 59-34zm-8 174c40 0 45-34 45-75 0-40-5-75-45-74-42 0-51 32-51 76 0 43 10 73 51 73" id="E"/><g id="f"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#t"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,11.11111111111111,0)" xlink:href="#D"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,23.45679012345679,0)" xlink:href="#E"/></g><g id="g"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#u"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,12.345679012345679,0)" xlink:href="#x"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,19.691358024691358,0)" xlink:href="#A"/></g><path fill="#333" d="M27 0v-27h64v-190l-56 39v-29l58-41h29v221h61V0H27" id="F"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#F" id="h"/><path fill="#333" d="M140-251c81 0 123 46 123 126C263-46 219 4 140 4 59 4 17-45 17-125s42-126 123-126zm0 227c63 0 89-41 89-101s-29-99-89-99c-61 0-89 39-89 99S79-25 140-24" id="G"/><path fill="#333" d="M30-248c118-7 216 8 213 122C240-48 200 0 122 0H30v-248zM63-27c89 8 146-16 146-99s-60-101-146-95v194" id="H"/><path fill="#333" d="M205 0l-28-72H64L36 0H1l101-248h38L239 0h-34zm-38-99l-47-123c-12 45-31 82-46 123h93" id="I"/><path fill="#333" d="M185-189c-5-48-123-54-124 2 14 75 158 14 163 119 3 78-121 87-175 55-17-10-28-26-33-46l33-7c5 56 141 63 141-1 0-78-155-14-162-118-5-82 145-84 179-34 5 7 8 16 11 25" id="J"/><g id="i"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#B"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,7.345679012345679,0)" xlink:href="#G"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,24.629629629629626,0)" xlink:href="#H"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,40.61728395061728,0)" xlink:href="#p"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,59.07407407407406,0)" xlink:href="#I"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,73.88888888888887,0)" xlink:href="#J"/></g><g id="j"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#z"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,6.172839506172839,0)" xlink:href="#y"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,18.51851851851852,0)" xlink:href="#t"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,29.62962962962963,0)" xlink:href="#z"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,35.80246913580247,0)" xlink:href="#C"/></g><path fill="#333" d="M115-194c55 1 70 41 70 98S169 2 115 4C84 4 66-9 55-30l1 105H24l-1-265h31l2 30c10-21 28-34 59-34zm-8 174c40 0 45-34 45-75s-6-73-45-74c-42 0-51 32-51 76 0 43 10 73 51 73" id="K"/><path fill="#333" d="M96-169c-40 0-48 33-48 73s9 75 48 75c24 0 41-14 43-38l32 2c-6 37-31 61-74 61-59 0-76-41-82-99-10-93 101-131 147-64 4 7 5 14 7 22l-32 3c-4-21-16-35-41-35" id="L"/><g id="k"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#B"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,7.345679012345679,0)" xlink:href="#K"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,19.691358024691358,0)" xlink:href="#x"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,27.037037037037038,0)" xlink:href="#u"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,39.382716049382715,0)" xlink:href="#r"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,51.72839506172839,0)" xlink:href="#D"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,64.07407407407408,0)" xlink:href="#L"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,75.18518518518519,0)" xlink:href="#z"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,81.35802469135803,0)" xlink:href="#s"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,86.23456790123457,0)" xlink:href="#u"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,98.58024691358025,0)" xlink:href="#v"/></g><g id="l"><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,0,0)" xlink:href="#K"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,12.345679012345679,0)" xlink:href="#x"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,19.691358024691358,0)" xlink:href="#u"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,32.03703703703704,0)" xlink:href="#r"/><use transform="matrix(0.06172839506172839,0,0,0.06172839506172839,44.382716049382715,0)" xlink:href="#C"/></g></defs></g></svg>
\ No newline at end of file

docs/shared-org-vs-sub-org.md

@@ -52,15 +52,23 @@ See the [Best Practices](./best-practices.md) for more information.
 This may be a drawback for some applications that need more development environments (e.g. dev, QA, staging).
 Objects can be named or organized to indicate a specific environment (e.g. "dev-mapping", "dev-project"), but having multiple development environments represented in a single org is not recommended.
 
-### Use a Separate Org with Sub-Orgs
+### Use a Sub-Org
 
-This option involves creating a new parent org with sub-orgs contained within it.
-The parent org would represent the production environment, with each sub-org representing a non-production environment.
-For example, you might have a sub-org for dev, a sub-org for test, and then the parent org for production.
+A sub-org is functionally equivalent to a parent org, except some aspects are inherited from the parent org.
+For example, a sub-org inherits licenses and connectors from the parent org. Currently, [ODMAS](https://data.wisc.edu/) group is provisioned in this way.
+
+
+![UW-Madison-IICS-org-hierarchy.](images/IICS-Organization-hierarchy.svg)
+
+The diagram source can be found [here](https://app.lucidchart.com/documents/edit/5b0329b6-a058-49d8-a379-25d31f48d91a/0_0?beaconFlowId=0AB69376446D424F#?folder_id=home&browser=icon).
 
-Unlike using the shared org, using this multi-org approach has extra financial costs. Depending on your needs, the Integration Platform Team might be able to help cover the extra cost. Please [contact us](mailto:doit-integration-platform@office365.wisc.edu) if this is something you would like to explore.
+- Parent org secure agent groups can also be shared to sub-orgs.
+- A sub-org cannot contain a sub-org. A sub-org can be created from within a parent org, or an existing org can be linked to a parent org to convert it into a sub-org.
 
-Here are cases when using this multi-org approach would be recommended:
+Unlike using the shared org, using a sub-org approach has extra financial costs. Depending on your needs, the 
+Integration Platform Team might be able to help cover the extra cost. Please [contact us](mailto:doit-integration-platform@office365.wisc.edu) if this is something you would like to explore.
 
-- More than one non-prod environment is needed, since the shared org approach only provides one test and one prod environment.
-- Many integrations are being built, requiring many objects. As a general rule, if you have over 30 projects or connections, this would be better managed by having your own org rather than using the shared org.
+Here are some recommendation when to use a sub-org:
+- Sub-orgs can be used for isolating different environments such as `test`, `qa` or `prod`. 
+- If your integration requires more than few integration assets and connections, then a sub-org may be a better fit.
+- If fine-grained authorization is needed within an sub-org, a user group can be applied to objects (e.g. assets, connections, secure agents) to limit access to a subset of sub-org users.
\ No newline at end of file