Creating Solution Patterns for Red Hat Managed Integration 2

Introducing Solution Patterns

Solution Patterns are templates that shorten development time and encourage best practices by providing opinionated instructions about how to develop cloud-native, integrated applications on your Red Hat Managed Integration cluster. You can create a Solution Pattern to communicate technical concepts and provide guidance for users in your organization. Your Solution Pattern should document a clear user story that addresses a goal.

To write a Solution Pattern you require a knowledge of:

AsciiDoc: A lightweight markup language that is similar to Markdown.
JSON: A lightweight format for storing and transporting data.
Git: An open source distributed version control system. You must push your AsciiDoc and JSON files to a Git repository accessbile from your cluster, for example, GitHub or GitLab.
OpenShift: A platform for developing and running containerized applications. You can add Solution Patterns using the OpenShift console.

You must create and edit an AsciiDoc file to contruct a Solution Pattern. The AsciiDoc file should resemble the following example:

= Demonstrating features (1)

A short description for the feature. (2)

== Doing a task (3)

. Do this first: (4)
. Do this second:

1	Solution Pattern title. Only one level 1 heading per file is allowed.
2	The Solution Pattern description is displayed on the Solution Explorer home page. Do not use AsciiDoc attributes in this line because they are not displayed correctly on the homepage.
3	Optional subtasks describe how to complete the task.
4	A numbered list of steps the user must perform.

Additional resources

For more information on writing in AsciiDoc, see the Asciidoc Homepage

Downloading the Solution Pattern template

To start developing your Solution Pattern, download the template repository. The template contains:

The directory structure
An example Solution Pattern
An example manifest file

Procedure

Clone the template repository

git clone https://github.com/integr8ly/walkthrough-template.git

Change to the walkthrough-template directory:
```
cd walkthrough-template
```

Solution Pattern file structure

.
├── walkthroughs-config.json (1)
└── walkthroughs(2)
    ├── <identifier> (3)
    │   ├── images (4)
    │   │   └── image.png
    │   ├── walkthrough.adoc (5)
    │   └── walkthrough.json (6)
    ├── <walkthrough2-id> (3)
    └── <walkthrough3-id> (3)

1	This is an optional file that defines metadata for the set of Solution Patterns in the repository.
2	This is a required directory. All Solution Patterns are defined under `walkthroughs`.
3	The directory name of a Solution Pattern. This is also displayed in the URL of the Solution Explorer.
4	All of the images for the Solution Pattern.
5	walkthrough.adoc is where the content of the Solution Pattern is written in AsciiDoc format.
6	walkthrough.json is the manifest file of the Solution Pattern where you can define dependencies.

The default walkthrough.json does not define any dependent services:

{
  "dependencies": {
    "repos": [],
    "serviceInstances": []
  }
}

Committing your Solution Pattern to a remote repository

Push your repository to GitHub or GitLab.

Procedure

Create a new remote repository and take note of the remote URL.
Add the remote repository as you upstream repository.
```
git remote add upstream <remote URL>
```
Commit the changes that you added to your local repository.
```
git commit -m "Add commit message"
```
Push the changes in your local repository to GitHub.
```
git push -u upstream master
```

Adding Solution Patterns to your Managed Integration cluster

The home page of the Solution Explorer lists the Solution Patterns from all the Git repositories you are subscribed to. Any developer can add Solution Patterns to your cluster.

This procedure describes how to subscribe your cluster to a Git repository that contains Solution Patterns.

Procedure

Navigate to the Solution Explorer.
Click the gear icon in the top right to display the Application settings screen.

Enter the URLs of the Solution Pattern Git repositories you want to add to your cluster using the following syntax:

https://github.com/<org>/<repo>.git

where <org> is the name of your GitHub organization and <repo> is the name of your repository.

List URLs in the order you want them to appear in the Solution Explorer.
Enter one URL per line.
To include a specific branch, append #<branch-name> to the url. For example:
```
https://github.com/<org>/<repo>.git#version-one
```

Click Save.

This triggers an automatic refresh of the Solution Explorer.
When the deployment is complete, refresh your browser.

You should now see new Solution Patterns available from the dashboard.
If the Git repository is updated with new content, the Solution Explorer is not automatically updated.

Refresh the Solution Explorer to view the changes:
1. Click the gear icon in the top right to display the Application settings screen.
2. Click Save to trigger a refresh of the Solution Explorer app.
3. When the Solution Explorer refresh is complete, refresh your browser.
4. Navigate to the Solution Patterns tab to see the updated content.

You can access the Git repository that contains the Solution Pattern source code by clicking the Repository link located in the upper right corner of each group of Solution Patterns on the All Solutions Patterns tab in the Solution Explorer.

Additional resources

To learn more about creating solution patterns, see the Creating Solution Patterns documentation.

Editing the overview section of a Red Hat Managed Integration Solution Pattern

The first section of the walkthrough.adoc describes your Solution Pattern. The overview section outlines the purpose of the Solution Pattern. The overview is displayed when a user clicks on the Solution Pattern in the Solution Explorer.

The overview is defined by the content before the first task.
The title of the overview is the name of the Solution Pattern.
The overview heading is followed by a short introduction to the Solution Pattern.

The overview description is displayed in the Solution Explorer dashboard for the Solution Pattern.

Prerequisites

You have created a repository using the Solution Pattern template.
You have added the Solution Pattern repository to your cluster as described in Adding Solution Patterns to your Managed Integration cluster.

Procedure

Edit the walkthroughs/1-template-walkthrough/walkthrough.adoc file.
Change the title of the Solution Pattern, for example:
```
= My first Solution Pattern
```
Add content for the overview section.
Commit your changes.
```
git commit -am "add overview"
```
Push your changes to the remote repository.
```
git push upstream master
```

To see your changes in Solution Explorer, refresh Solution explorer by clicking the gear icon followed by Save.

Editing task sections of a Red Hat Managed Integration Solution Pattern

Tasks are procedures in the walkthrough.adoc file that guide a user through a Solution Pattern.

You can create another level of subtasks by creating a third level heading (===). Subtasks are displayed in the Solution Explorer on the parent task page.

Prerequisites

You have created a repository using the Solution Pattern template.
You have added the Solution Pattern repository to your cluster as described in Adding Solution Patterns.

Procedure

Edit the walkthroughs/1-template-walkthrough/walkthrough.adoc file.
Change the task title, for example:
```
== Doing the first task
```
Write a introduction about the task.
Change the task timing estimate. Each task has an attribute to communicate the approximate time that the task should take the user to perform.

This is displayed in the Solution Pattern overview as part of the task list.

For example to change the estimated time for the first task to 12 minutes:
```
[time=12]
== Doing the first task
```
Edit the numbered list:
```
. First step
. Second step
. Third step
```
Save, commit, and push your changes.

The content of the Solution Explorer does not change automatically after a change in the subscribed repository. You must redeploy the Solution Explorer for the change to be visible.
Redeploy the Solution Explorer:
1. Click the gear icon in the top right to display the Application settings screen.
2. Click Save to trigger a redeployment of the Solution Explorer app.
3. When the deployment is complete, refresh your browser.
4. Navigate to the Solution Patterns tab to see the updated content.

Editing procedures of a Red Hat Managed Integration Solution Pattern

A procedure is a set of steps that you perform to complete a task or subtask.

Write procedures using AsciiDoc numbered lists. Prepend each step with a dot (.) to create a simple numbered list.

Prerequisites

You have created a repository using the Solution Pattern template.
You have added the Solution Pattern repository to your cluster as described in Adding Solution Patterns to your Managed Integration cluster.

Procedure

To edit a procedure in the template respository:

Edit the walkthroughs/1-template-walkthrough/walkthrough.adoc file.
Edit the numbered list:
```
. First step
. Second step
. Third step
```
Save, commit, and push your changes.

To see your changes in Solution Explorer, refresh Solution explorer by clicking the gear icon followed by Save.

Editing resources for a Red Hat Managed Integration Solution Pattern

The Solution Explorer displays information and links on the right side pane in Solution Explorer. You can add Solution Pattern resources by using block attributes. You can only define Solution Pattern resources in the overview section.

Setting serviceName is optional.
If serviceName is set to the name of a Red Hat Middleware service, an icon indicating the service status is displayed next to the resource.
For a list of default services, see the value for DEFAULT_SERVICES.
Setting the window="_blank" parameter for a Solution Pattern resource link is also optional, but ensures that the target of the link displays in a separate browser tab.

Prerequisites

You have created a repository using the Solution Patterns template.
You have added the Solution Pattern repository to your cluster as described in Adding Solution Patterns to your Managed Integration cluster.

Procedure

Edit the walkthroughs/1-template-walkthrough/walkthrough.adoc file.

Add Solution Pattern resources using block attributes to the end of the overview section, for example:

[type=walkthroughResource,serviceName=openshift]
.OpenShift
****
* link:{openshift-host}[Openshift Console, window="_blank"]
****

Save, commit, and push your changes.

To see your changes in Solution Explorer, refresh Solution explorer by clicking the gear icon followed by Save.

Editing task resources for a Red Hat Managed Integration Solution Pattern

The Solution Explorer displays helpful information and links on the right side panel that are specific to a task. Solution Pattern resources are displayed for every task. Task resources typically change as you navigate the Solution Pattern.

Prerequisites

You have created a repository using the Solution Pattern template.
You have added the Solution Pattern repository to your cluster as described in Adding Solution Patterns to your Managed Integration cluster.

Procedure

Edit the walkthroughs/1-template-walkthrough/walkthrough.adoc file.

At the end of any task section, add the following:

[type=taskResource]
.Useful links
****
* link:https://google.com[Task related link]
****

Save, commit, and push your changes.

To see your changes in Solution Explorer, refresh Solution explorer by clicking the gear icon followed by Save.

Adding verifications to a Red Hat Managed Integration Solution Pattern

Verifications are interactive elements in a Solution Pattern that confirm whether a user has successfully completed a procedure. They are questions presented to the user, which can be answered with either a Yes or No response.

Prerequisites

You have created a repository using the Solution Pattern template.
You have added the Solution Pattern repository to your cluster as described in Adding Solution Patterns to your Managed Integration cluster.

Procedure

Edit the walkthroughs/1-template-walkthrough/walkthrough.adoc file.

At the end of the procedure section following the numbered list, add:

[type=verification]
Check that the dashboard of service X reports no errors.

Add the following block for users that answer the question with No:
```
[type=verificationFail]
Try turning it off and on again.
```
Save, commit, and push your changes.

To see your changes in Solution Explorer, refresh Solution explorer by clicking the gear icon followed by Save.

Adding attributes to a Red Hat Managed Integration Solution Pattern

Attributes enable you to use variables in your Solution Pattern. The syntax for using attributes is {<attribute name>}. Solution Patterns have access to predefined attributes:

Access a Middleware service defined route: {route-<route name>-host}
AMQ Online Broker URL: {enmasse-broker-url}
AMQ Online Credential Username: {enmasse-credentials-username}
AMQ Online Credential Password: {enmasse-credentials-password}
AMQ Online URL: {enmasse-url}.
CodeReady Workspaces URL: {che-url}.
API Management URL: {api-management-url}
Fuse URL: {fuse-url}
Launcher URL: {launcher-url}
OpenShift console: {openshift-host}
OpenShift app host: {openshift-app-host}

Prerequisites

You have created a repository using the Solution Pattern template.
You have added the Solution Pattern repository to your cluster as described in Adding Solution Patterns to your Managed Integration cluster.

Procedure

Edit the walkthroughs/1-template-walkthrough/walkthrough.adoc file.

Add another step and include the attribute value:

. Log in to the link:{openshift-url}[Red Hat OpenShift Console].

Save, commit, and push your changes.
Redeploy the Solution Explorer:
1. Click the gear icon in the top right to display the Application settings screen.
2. Click Save to trigger a redeployment of the Solution Explorer app.
3. When the deployment is complete, refresh your browser.
4. Navigate to the Solution Patterns tab to see the updated content.

Define metadata for your Solution Pattern repository

By default, the Solution Patterns from a repository are displayed in the Solution Explorer with a title corresponding to your repository name. You can add a walkthroughs-config.json file with the following content if, for example, you want to title the group My Solution Patterns:

{
    "prettyName": "My Solution Patterns"
}