Removed th requirement for BM credenitals. Now data import job can be…

… run with just the OCAPI credentials.
jenkinsci · Dec 12, 2019 · c3c1e49 · c3c1e49
1 parent 5b4254d
commit c3c1e49
Show file tree

Hide file tree

Showing 22 changed files with 940 additions and 826 deletions.
diff --git a/README.md b/README.md
@@ -1,2 +1,263 @@
 # OSF Builder Suite For Salesforce Commerce Cloud :: Data Import
 Import your site data to a Salesforce Commerce Cloud instance
+
+**OSF Builder Suite For Salesforce Commerce Cloud :: Data Import** is a very easy-to-use and highly configurable Jenkins plugin that is used to automate data imports to your Salesforce Commerce Cloud continuous integration sandbox, development or staging instance.
+
+If you have a bug to report or maybe a feature that you wish to request, please do so [on GitHub, on the project's issues page](https://github.com/jenkinsci/osf-builder-suite-for-sfcc-data-import-plugin/issues).
+
+
+# Features
+
+- Simple. It does one thing, and it does it well.
+- Easy to install, use and keep updated.
+- Easy to configure. The plugin can be configured from the Jenkins web interface.
+- Support for classical mode, Jenkins [Pipelines](https://jenkins.io/doc/book/pipeline/) and also the new modern [Blue Ocean](https://jenkins.io/doc/book/blueocean/) interface.
+- Super flexible. Every little thing is configurable so that the plugin can be easily adjusted to your workflow.
+- Integrated with the Jenkins [credentials plugin](https://plugins.jenkins.io/credentials) so that your credentials are safely stored encrypted.
+- Support for two factor authentication
+- Good documentation. Every option is documented both here on this page but also inline in Jenkins's UI by clicking the question mark icon next to the item for which you wish to display the help information.
+- Support for HTTP proxy with basic or [NTLM](https://en.wikipedia.org/wiki/NT_LAN_Manager) authentication.
+- Free
+- Open source
+- Fast builds. The data is checked for changes and if nothing changed the build is skipped so that you don't import same unchanged data over and over again.
+
+
+# Installation
+
+Just go to `Manage Jenkins > Manage Plugins > Available`, search for `OSF Builder Suite`, select `OSF Builder Suite For Salesforce Commerce Cloud :: Data Import` and click `Download now and install after restart` button.
+
+
+# Configuration
+
+![](imgs/hostname.png)
+
+Hostname of the SFCC instance where this build should be deployed. Examples:
+
+|                                              |                                                                                   |
+| -------------------------------------------: | :-------------------------------------------------------------------------------- |
+| `cert.staging.realm.customer.demandware.net` | For deployments to a staging instance that has two factor auth enabled.           |
+|      `staging-realm-customer.demandware.net` | For deployments to a staging instance that does not have two factor auth enabled. |
+|  `development-realm-customer.demandware.net` | For deployments to a development instance.                                        |
+|        `devNN-realm-customer.demandware.net` | For deployments to a sandbox instance.                                            |
+
+![](imgs/tf_credentials.png)
+
+Two Factor Auth credentials of type `OSF Builder Suite :: Two Factor Auth Credentials` for the SFCC instance where this build should be deployed. Select `- none -` if you deploy to a instance that does not require two factor auth.
+
+![](imgs/oc_credentials.png)
+
+Open Commerce API credentials of type `OSF Builder Suite :: Open Commerce API Credentials` for the SFCC instance where this build should be deployed.
+
+![](imgs/oc_version.png)
+
+The version to be used by the calls made to OCAPI. The Open Commerce API Version starts with the character `v` (lowercase) followed by the actual version number, separated by an underscore.
+
+For example: `v19_10`
+
+![](imgs/archive_name.png)
+
+Name of the zip file that will be created by compressing your data that will be uploaded to your target instance and then imported. Only the name, without the `.zip` extension as it will be added by the plugin automatically. 
+
+For example: `metadata`
+
+
+![](imgs/source_path.png)
+
+Path (relative to the workspace) to a directory where the builder will look for data to be imported. 
+
+For example: `scm/my-git-repo/metadata`
+
+
+![](imgs/exclude_patterns.png)
+
+You can also define a list of patterns to be ignored. If a path matches any of the patterns in this list then it will be ignored and not added to the build. The pattern needs to be relative to the source path defined above.
+
+When a path is matched against a pattern, the following special characters can be used:
+
+|      |                                                                 |
+| ---: | --------------------------------------------------------------- |
+|  `?` | Matches one character (any character except path separators)    |
+|  `*` | Matches zero or more characters (not including path separators) |
+| `**` | Matches zero or more path segments                              |
+
+Examples:
+
+|                        |                                                                                                                                  |
+| ---------------------: | -------------------------------------------------------------------------------------------------------------------------------- |
+|              `**/*.js` | Matches all .js files/dirs in a directory tree                                                                                   |
+|      `node_modules/**` | Matches the node_modules folder and all its contents                                                                             |
+|          `test/a??.js` | Matches all files/dirs which start with an a, then two more characters and then .js, in a directory called test                  |
+|                   `**` | Matches everything in a directory tree                                                                                           |
+|      `**/test/**/XYZ*` | Matches all files/dirs which start with XYZ and where there is a parent directory called test (e.g. abc/test/def/ghi/XYZ123)     |
+
+
+![](imgs/tmp_dir.png)
+
+Path (relative to the workspace) to a temp directory, that will be used during the build. If the directory does not exist, it will be created by the builder and it will also be automatically cleaned up before each build.
+
+For example: `tmp/metadata`
+
+
+![](imgs/proxy_host.png)
+
+If your Jenkins server sits behind a firewall and does not have direct access to the internet, you can specify the HTTP proxy host in this field to allow Jenkins to connect to the internet trough it.
+
+![](imgs/proxy_port.png)
+
+This field works in conjunction with the proxy host field to specify the HTTP proxy port.
+
+![](imgs/proxy_username.png)
+
+This field works in conjunction with the proxy host field to specify the username used to authenticate with the proxy.
+
+If this proxy requires Microsoft's [NTLM](https://en.wikipedia.org/wiki/NT_LAN_Manager) authentication scheme then the domain name can be encoded within the username by prefixing the domain name followed by a back-slash `\` before the username, e.g `ACME\John Doe`.
+
+![](imgs/proxy_password.png)
+
+This field works in conjunction with the proxy host field to specify the HTTP proxy password.
+
+![](imgs/ssl_validation.png)
+
+When this option is checked, the builder will no longer validate the SSL certificate and hostname of the target instance.
+
+**This has potential security implications so make sure you know what you are doing before enabling this option!**
+# **Open Commerce API Settings**
+Go to `Administration > Site Development > Open Commerce API Settings`, select type `Data`, select context `Global` and add following configuration:
+
+```JSON
+{
+    "_v": "19.10",
+    "clients": [
+        {
+            "client_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            "resources": [
+                {
+                    "resource_id": "/code_versions/*",
+                    "methods": ["put", "patch"],
+                    "read_attributes": "(**)",
+                    "write_attributes": "(**)"
+                },
+                {
+                    "resource_id": "/jobs/*/executions",
+                    "methods": ["post"],
+                    "read_attributes": "(**)",
+                    "write_attributes": "(**)"
+                },
+                {
+                    "resource_id": "/jobs/*/executions/*",
+                    "methods": ["get"],
+                    "read_attributes": "(**)",
+                    "write_attributes": "(**)"
+                }
+            ]
+        }
+    ]
+}
+```
+
+Go to `Administration > Organization > WebDAV Client Permissions` and add following configuration:
+
+```JSON
+{
+    "clients": [
+        {
+            "client_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            "permissions": [
+                {
+                    "path": "/cartridges",
+                    "operations": [
+                        "read_write"
+                    ]
+                },
+                {
+                    "path": "/impex",
+                    "operations": [
+                        "read_write"
+                    ]
+                }
+            ]
+        }
+    ]
+}
+
+```
+
+
+# Jenkins Pipeline Configuration
+Here's a sample pipeline configuration to get you started:
+
+```Groovy
+node {
+    stage('Cleanup') {
+        cleanWs()
+    }
+
+    stage('Git') {
+        dir('scm/github.com/???/???') {
+            git(
+                branch: '???',
+                credentialsId: '???',
+                url: 'git@github.com:???/???.git'
+            )
+        }
+    }
+
+    stage('Yarn') {
+        dir('scm/github.com/???/???') {
+            nodejs('NodeJS v12') {
+                sh('yarn install')
+            }
+        }
+    }
+
+    stage('Build') {
+        dir('scm/github.com/???/???') {
+            nodejs('NodeJS v12') {
+                sh('yarn run webpack:prd')
+            }
+        }
+    }
+
+    /* See https://plugins.jenkins.io/osf-builder-suite-for-sfcc-deploy
+    stage('CodePush') {
+        osfBuilderSuiteForSFCCDeploy(
+            hostname: '???',
+            tfCredentialsId: '???',
+            ocCredentialsId: '???',
+            ocVersion: 'v19_10',
+            buildVersion: 'dev',
+            sourcePaths: [[sourcePath: 'scm/github.com/???/???/cartridges']],
+            activateBuild: true,
+            createBuildInfoCartridge: true,
+            tempDirectory: 'tmp/code'
+        )
+    }
+    */
+
+    stage('DataPush') {
+        osfBuilderSuiteForSFCCDataImport(
+            hostname: '???',
+            tfCredentialsId: '???',
+            ocCredentialsId: '???',
+            ocVersion: 'v19_10',
+            archiveName: 'metadata',
+            sourcePath: 'scm/github.com/???/???/metadata',
+            importStrategy: 'DELTA',
+            tempDirectory: 'tmp/data'
+        )
+    }
+}
+```
+
+You can also always consult the pipelines documentation available at <https://jenkins.io/doc/book/pipeline/> or check the pipeline syntax link right inside Jenkins on the left navigation menu.
+
+![](imgs/left_nav.png)
+
+# Version history
+<https://github.com/jenkinsci/osf-builder-suite-for-sfcc-data-import-plugin/releases>
+
+
+# Dev
+- `mvn hpi:run`
+- `mvn clean package hpi:hpi`
+- `mvn release:prepare release:perform`
diff --git a/imgs/archive_name.png b/imgs/archive_name.png
diff --git a/imgs/exclude_patterns.png b/imgs/exclude_patterns.png
diff --git a/imgs/hostname.png b/imgs/hostname.png
diff --git a/imgs/left_nav.png b/imgs/left_nav.png
diff --git a/imgs/oc_credentials.png b/imgs/oc_credentials.png
diff --git a/imgs/oc_version.png b/imgs/oc_version.png
diff --git a/imgs/proxy_host.png b/imgs/proxy_host.png
diff --git a/imgs/proxy_password.png b/imgs/proxy_password.png
diff --git a/imgs/proxy_port.png b/imgs/proxy_port.png
diff --git a/imgs/proxy_username.png b/imgs/proxy_username.png
diff --git a/imgs/source_path.png b/imgs/source_path.png
diff --git a/imgs/ssl_validation.png b/imgs/ssl_validation.png
diff --git a/imgs/tf_credentials.png b/imgs/tf_credentials.png
diff --git a/imgs/tmp_dir.png b/imgs/tmp_dir.png
diff --git a/pom.xml b/pom.xml
@@ -11,7 +11,7 @@
     </parent>
 
     <artifactId>osf-builder-suite-for-sfcc-data-import</artifactId>
-    <version>1.0.10-SNAPSHOT</version>
+    <version>1.1.0-SNAPSHOT</version>
     <packaging>hpi</packaging>
 
     <name>OSF Builder Suite For Salesforce Commerce Cloud :: Data Import</name>
@@ -134,14 +134,14 @@
         <dependency>
             <groupId>org.apache.commons</groupId>
             <artifactId>commons-lang3</artifactId>
-            <version>3.8.1</version>
+            <version>3.9</version>
         </dependency>
 
         <!-- https://mvnrepository.com/artifact/org.apache.commons/commons-text -->
         <dependency>
             <groupId>org.apache.commons</groupId>
             <artifactId>commons-text</artifactId>
-            <version>1.6</version>
+            <version>1.8</version>
         </dependency>
 
         <!-- https://mvnrepository.com/artifact/commons-codec/commons-codec -->
@@ -155,7 +155,7 @@
         <dependency>
             <groupId>org.apache.httpcomponents</groupId>
             <artifactId>httpclient</artifactId>
-            <version>4.5.7</version>
+            <version>4.5.10</version>
         </dependency>
 
         <!-- https://mvnrepository.com/artifact/org.zeroturnaround/zt-zip -->
@@ -183,7 +183,7 @@
         <dependency>
             <groupId>org.codehaus.plexus</groupId>
             <artifactId>plexus-utils</artifactId>
-            <version>3.1.1</version>
+            <version>3.3.0</version>
         </dependency>
 
         <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->