Merge pull request #10535 from mendix/nc-split-best-practices

Restructure Best Practices for Creating Connectors

Author: NicoletaComan

content/en/docs/marketplace/create-content/create-connectors/_index.md

@@ -87,7 +87,7 @@ To start setting up your app, open Studio Pro and do the following:
 3. Give your module a name fitting for the type of connector you are building.
 4. Create the basic folder structure at root level. 
 
-For more information, see the [App Setup](/appstore/creating-content/connector-guide-best-practices/#app-setup) section of *Best Practices for Building Connectors*.
+For more information, refer to [App Setup](/appstore/creating-content/best-practices/app-setup/).
 
 ### Implementing the Connector {#implement}
 

content/en/docs/marketplace/create-content/create-connectors/connector-best-practices/_index.md

@@ -0,0 +1,13 @@
+---
+title: "Best Practices for Creating Connectors"
+url: /appstore/creating-content/connector-guide-best-practices/
+weight: 7
+no_list: false
+description_list: true
+---
+
+## Introduction
+
+The following pages provide details and recommended best practices for building, testing, and distributing connectors. 
+
+## Documents in this Category

content/en/docs/marketplace/create-content/create-connectors/connector-best-practices/app-setup.md

@@ -0,0 +1,69 @@
+---
+title: "App Setup"
+url: /appstore/creating-content/best-practices/app-setup/
+weight: 8
+---
+
+## Introduction {#app-setup}
+
+This section dives into best practices for setting up your app in Studio Pro. For basic instructions, refer to the [Setting Up Your App](/appstore/creating-content/connector-guide-build/#app-setup) section of *Creating Connectors*.
+
+## Studio Pro Version
+
+For people to use your connector, ensure that you are not only targeting end-users that have the latest version Studio Pro. Try to support the latest [LTS](/releasenotes/studio-pro/lts-mts/) version and, if possible, even older supported versions. 
+
+The only reason to deviate from this is when your connector requires a certain platform functionality that is only available in a newer version, or requires another module that is only available on a newer version. In that case, use that newer version as your Mendix required version.
+
+## Modules in the App
+
+Create a Mendix app in Studio Pro with the main connector module and a testing module. You can also add an example module showing some use cases.
+
+* The main module contains all the logic needed to let your connector function in apps that import it. Give the main module the name you want to appear in apps after others import your module.
+* The testing module has microflows, pages, and Java code to test your module's functionality. This means that you will not have to add the test logic to the module that you will later export and publish.
+* You can publish the example module next to the connector main module and testing module to help end-users better understand the implementation of your connector module, or to try it out without having to do too much configuration from the start.
+
+### Setting Up the Main Connector Module {#main-setup}
+
+Mendix recommends that the main module for your connector include the following:
+
+* **_Docs** (folder) – Contains documentation or a reference to documentation, and a version indicator.
+    * **ReadMe** (snippet) – Used to give a reference to documentation and/or some direct documentation on how to use the module.
+    * **[ModuleName]_[Version]** (string constant) – Replace [ModuleName] with the name of your module, and [Version] with the version of the module. Use the same standard as the Mendix Marketplace 1.2.3. Refer to the [Versioning](/appstore/creating-content/best-practices/releasing-versioning/#versioning) section in *Releasing and Versioning*.
+        * As an alternative to the version constant, you can include a subfolder with the version indication.
+* **Private** (folder) – This folder contains all the logic that other developers should not touch when implementing your module.
+* **UseMe** (folder) – Contains everything the implementing developer could use to implement your module in their application. It can include subfolders for **Microflows**, **Pages**, **Snippets**, **Templates**, and **Constants**.
+
+Your **App Explorer** should look like this after the initial setup:
+
+{{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/app-initial-setup.png" class="no-border" >}}
+
+{{% alert color="info" %}}
+This app folder structure example is based on the **Blank Web App** starter app, and contains Mendix Marketplace modules that your app might not have. The important Marketplace module that is shown is the [Unit Testing](/appstore/modules/unit-testing/) module for testing purposes.
+{{% /alert %}}
+
+### Setting Up the App Root {#root-setup}
+
+Mendix recommends adding additional folders to the root of your app, on disk. These include the following:
+
+* **DIST** – This contains the releases of your module kept for reference.
+* **MarketplaceResources** – This contains all the assets used in the Mendix Marketplace, such as screenshots, videos, and reference documents. It does not contain the release packages.
+
+The app root of your **App Explorer** should look like this after root setup:
+
+{{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/app-post-setup.png" class="no-border" >}}
+
+### Importing Dependency Modules
+
+Use as few dependency modules as possible. When you must use one, make sure it is either platform supported or, if you are creating a company-only connector, maintained by your own company. This ensure that users are are always supported. Otherwise, you might end up having to maintain those public non-platform supported modules to ensure that your connector operates properly.
+
+## Adding the App to Version Control
+
+If you have not already added your app, add it to the [Team Server](/refguide/version-control/#team-server). An alternative solution that Mendix recommends is having a separate public Git repository next to your private Team Server Git repository. This way, you can continue committing and applying changes while you only push to the public repository for a new release to the Marketplace. The automated integration with GitHub from the Marketplace makes this a good option for your public-facing Git repository.
+
+## Working with Java-Intensive Apps
+
+For Java-intensive apps, consider creating an **Implementation** submodule to keep core implementation separate. You can also make the module a Gradle project in order to better manage dependencies and the release pipeline. Create the *gradle.build* file to manage Java library dependencies and the cleanup of the **userlib** folder for export. For further information, refer to [Extending App Setup for Building Connectors with Java](/appstore/creating-content/best-practices/development/#extend-app-java) in *Development*.
+
+## Licensing
+
+Follow your Java Libraries and default to Mendix EULA. Also, Mendix recommends that you do not use copy-left licenses for commercially available connectors.

content/en/docs/marketplace/create-content/create-connectors/connector-best-practices/configuration.md

@@ -0,0 +1,100 @@
+---
+title: "Configuration"
+url: /appstore/creating-content/best-practices/configuration/
+weight: 10
+---
+
+## Introduction
+
+You should set up your configuration in such a way as to ensure that your connector can be used in different settings without changes to the module itself. This means that upon deployment or after deployment your connector can be configured to connect to the relevant services. 
+
+Using constants is the way to deal with configuration that aligns with the [Twelve-Factor Architecture](https://www.mendix.com/evaluation-guide/enterprise-capabilities/twelve-factor-architecture/) cloud-native approach.
+
+## Simple Configuration
+
+When you are looking for a simple configuration, such as a URL, username, or password, you can use [constants](/refguide/constants/). Constants are ideal for simple flat configurations.
+
+### Simple Configuration with a Free App Environment
+
+When using constants in combination with a Free App, you can use the settings profile to allow for different configurations. Follow these steps to do that:
+
+1. Create a constant.
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/simple-config-constant.png">}}
+
+2. Set the value of the constant to the value you want to use in your free cloud node.
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/simple-config-value.png" >}}
+
+3. Open your application **Settings**. 
+
+4. Click **Duplicate** or **New** to create a new configuration for your local usage.
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/simple-config-settings.png">}}
+
+5. In your configuration, open the **Constants** tab and click **New**.
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/simple-config-new-constants.png">}}
+
+6. Look up and select your constant.
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/simple-config-select-constant.png">}}
+
+7. Change the configuration value of your constant to the value you want to use in your local environment.
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/simple-config-change-value.png">}}
+
+8. Save the configuration and publish the application to your free node. When you run locally, Studio Pro will now use the **Active** configuration, while the free cloud node will keep using the value you specified in the **App Explorer**.
+
+## Complex Configuration
+
+You might need a more sophisticated configuration to connect to external systems, either because you will need to have dozens of constants or you want to be able to connect to multiple endpoints without having to replicate your constants each time. You will have to maintain these through configuration tables.
+
+### Disadvantages of Complex Configuration
+
+The following are the disadvantages of complex configuration:
+
+* Configuration in the database or the codebase makes it difficult to deploy your connector/app to any new environment.
+* Manual configuration could cause more mistakes.
+* Restoring a database to a different environment when the configuration is stored in the database could cause unwanted behavior.
+* One big risk of using the database to store configuration is test data going out to production users.
+
+### Advantages of Complex Configuration
+
+The following are the advantages of complex configuration: 
+
+* It provides more complexity than constants.
+* You can easily perform runtime changes on the configuration.
+* You can add wizards/helper flows to guide the user with the configuration.
+
+### Setting Up Complex Configuration
+
+Follow these steps to set up complex configuration: 
+
+1. Set up a **Configuration** entity.
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/complex-config-entity.png">}}
+
+2. Create the microflow.  
+   Have a single microflow called **DS_GetOrCreateSettings**. It will retrieve your settings from the database, and create it with appropriate default values if it does not exist.
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/complex-config-create-microflow.png">}}
+
+3. Set up security on the entity and the microflow.
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/complex-config-security.png" >}}
+
+    {{< figure src="/attachments/appstore/create-content/create-connectors/connector-guide-best-practices/complex-config-security-2.png" >}}
+
+4. Set up the administrator page.  
+   Have an administration page to manage the configuration. For maximum reusability, have all configuration settings available in a single snippet so your consumer can combine all admin sections from all components into a single area in their application.
+
+5. Encrypt the password and other sensitive information.
+
+#### Further Considerations
+
+When possible, create a microflow to set up the default or starting configuration for your consumers. 
+
+Consider adding logic so the configuration can easily be set up from your codebase.
+
+If possible, add an export/import option for the configuration to safely move the configuration between environments. This could be achieved via a JSON export/import of the configuration data.