Master component examples

The component details consist of details about the artifact for which the component is based. It can include where the artifacts are stored (the source or repository server), artifact name, artifact version,the directory where the artifact can be retrieved, and so on. You can parameterize part of the artifact definition to account for variations in the artifact details every time you deploy the application. This allows you to reuse the master component in multiple deployment scenarios. For example, you can create a master component that has a standard process to deploy and undeploy, and the only thing that changes is which specific artifact to use based on parameters.
Component processes are defined in the application process steps. The component processes are used to define the automation steps to perform on the artifact that is defined in the component details. These processes can be used to deploy, undeploy or do any other action. Each master component can have one or more component processes, and each process can have specific automation steps. These steps can describe how to perform specific tasks such as publish or retrieve an artifact, stop a server process, copy files, restart the server, and so on. A master component must have one or more component processes. You can parameterize master component processes so that certain behaviors can be achieved when master components are used in application definition. For example, you can have port number as a component process parameter for a master component, and have different values for port number in different application models where this master component is used.

This example shows how to create a master component, create parameters for the artifact definition, define the component processes, create parameters for the component processes, and use the master component in an application, promoting the component reuse throughout your organization. It does not include how to author applications and environments or how to deploy the application. For information about these tasks, see the example in Model and deploy traditional applications.

In the following steps, you will learn how to:

Create a master component and parameters for the artifact definition.
View the master component details.
Use master components in an application.

Create a master component and parameters for the artifact definition

This section shows how to create a new master component and create parameters for the artifact definition.

Access the Master components screen from the main menu, and select Deployment automation Master components.

Figure 1. Master components for all projects

By default, the master components for all projects are displayed. Use the Filters function to limit the display. For example, to view Master components whose owner is admin:

Select .
Choose a field to limit the display. For example, "Owner".
Choose an operator. For example, "Equals".
Add a valid value to limit the display. For example, "admin".

To view only the objects for a specific project, select the down arrow in the All projects field and select one or more projects in one of the following ways:

Select the name of one or more projects.
Enter the search criteria in the Search field. The projects that match the criteria display in the list.

If there are no matches, a message displays stating that there are no resource templates in the selected projects.

Create a new master component

On the Master components window select the New button. The New dialog box opens.
Select Create New.
Enter a name.
Select the project for which the master component belongs.
(Optional) add a description.
(Optional) configure Tags.

Include URL links as part of the description for any CloudBees CD/RO object.
Select Next.

The Component Definition page dialog box opens.
Select the Content location option. For this example, select EC-Maven.
Enter the information about the artifact.

The available configuration options vary based on the selected content location.

For EC-Maven, enter the following required information for this component. If you select another plugin, this information may not be required.

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].
- Public Server URL: https://repo-demo.jfrog.org/artifactory/
- Repository: jboss-releases
- Artifact: org.jboss.el:jboss-el
- Version: Exact
- Artifact extension: jar
Select OK.

The Master component now appears in the list.

Create a parameter

In this example, the artifact name is parameterized and jboss-el is replaced with a variable. Enter the information in the Artifact field.

Navigate to the row for the master component, select the Actions , and then select Parameters. The Parameters dialog opens.
Select , or if no parameters have been defined for the object, select There are no Parameters. Add one +. The New Parameter dialog opens.
In the New Parameter dialog box, enter the parameter settings.
- In the Name field, enter artifactName.
- In the Label field, enter Artifact Name.
  
  Keep the rest of the fields as they are
  
  The parameter is required. Enter a value for this parameter when this master component is used in an application.
Select OK and dismiss the dialog.
Locate the row for the new master component, and select Actions .
Select Component Definition to modify the artifact definition with the artifact-name parameter.
In the Component Details dialog box, locate the Artifact field and replace jboss-el with $[artifactName].
Select OK.

You have now created a master component with one parameter for the artifact definition.

Additional methods for creating a master component from the Master components screen, after selecting New + are as follows:

Copy Application Component…
- Select "Copy application component".
- Select the associated project.
- Select the application component to be copied.
- (Optional) add a description and tags.
- Select OK.
Copy master component…
- Select "Copy master component…".
- Select an existing component on the From existing… dialog box.
- Select the associated project.
- (Optional) add a description and tags.
- Select OK.

The next step is to add processes to the master components and create parameters for the processes.

Author component processes and create parameters

This section shows how to author component processes for the master component created in the previous section and create parameters for those processes.

Starting in the Master Component list:

Locate the master component that you created, and select .
Select Add process.

The New master component process dialog box opens.
Select Create new….
Enter a name for the component process.
Select the process type: Deploy, Undeploy, or Other.
Select a Workspace.
(Optional) add remaining attributes as needed.
Select OK. The Master components editor window opens.
Select to define the component process step in the Component Process Visual Editor.

For detailed instructions and examples, refer to Author component processes.

Once the new master component process is defined, the Master components visual editor updates showing the newly defined step.
Select the Deploy process.

The Component Process visual editor opens.

Figure 2. Component process visual editor
Select the on the right pane and then select Parameters.
Select , or if no parameters are defined, select There are no Parameters yet. Add one * to add a parameter. The New Parameter dialog opens.
Complete the New Input Parameter dialog.

Use the following as example input:
- In the Name field, enter portNumber.
- In the Label field, enter Port Number.
  
  Keep the rest of the fields as they are.
  
  This parameter has no default value and is required. The user must enter a port number when this master component is used in an application.
Select OK.

The port number parameter is created for the Deploy process. The Parameters dialog box shows that the port number parameter is required for the Deploy process.
Close the Parameters dialog box.
Reference the master component in an application, or copy it to an application.
- To reference the master component in an application, refer to Reference master components in an application.
- To copy the master component to an application, refer to Copy a master component to an application.
  
  After you add the component to an application tier, a dialog box appears prompting you to enter values for the parameters for the master component process, starting with this step.

You have now authored component processes for the master component and have created a parameter for it.

View the master component details

You can ensure that the artifact definition and component process step defined by the master component are correct by viewing the master component details in the following places. They first appear in the artifact definition.

They also appear in the component process step details. When you view the component process details for the Deploy process in the Component Process Editor, you can see that the Deploy process consists of one step called Retrieve, which is defined by the jboss-mc-prod master component.

Use master components in an application

After master components have been defined, they can be used in application models. There are two ways to leverage master components in an application:

Reference master components in an application.
Copy a master component to an application.

To review the implications of these methods, refer to Create master components.

Reference master components in an application

When you reference a master component in an application, it is added to the application as an application component with the same definition, processes, parameters, and properties as the referenced master component. Any changes made to the master component will affect all the application components that reference it.

Use the reference method when the component is used in multiple applications, and you want to ensure that these application components continue to inherit all changes made to the master component. This section shows how to author a new application that references the master component created in the previous sections.

Go to Deployment automations Applications.
Select Add application. The New Application dialog box opens.
Select Create New… to create an application.
Enter an application name.
Select a project where the applications in the pipeline will be deployed.
(Optional) add a description.
Select the Application type. By default, Traditional is selected. Refer to, Model and deploy traditional applications, Model and deploy microservice applications, or Create a deployment task to trigger third-party tools for more information.
(Optional) configure Object Tags.
Select OK.

The Application editor opens.
Define the Application tier (Tier 1). Refer to Create applications and processes for more information.
Select in the application tier and select Details to open the Applications Tier, Details dialog box.
Change the tier name to Data in the Name field.
Select OK to rename the application tier.

The Application Editor now shows one environment tier called Data.
Select + in the component to add a component to the application tier.
Select Create from existing master component.

A list showing all available the master components opens. You can also create a new application component using one of these options:
- Refer to the new application documentation to use the Create a new application component dialog.
- Create from existing application component —this opens the Create from existing component dialog box.
  
  Choose Select Application, and then select an application. Select the Select Tier field and select an application tier. A list of components in the selected application and application tier appears. Select a component from this list.
In the Create a reference to a master list, select a master component.

In this example, select the master component called jboss-mc-prod.
Select Next.

The Create from existing component dialog box opens.
In the New dialog box, change the name to jboss-mc-results, select Next.
Select Next.

If the master component has parameter for its artifact definition, you are prompted to enter values for those parameters in the next step.

If the component does not have parameters for its artifact definition, select OK. Then go to the Component Process Visual Editor and add a parameter to the component, starting at Step 9 in Create a master component and parameters for the artifact definition.
Enter the values for the parameters.
Select OK.

The jboss-mc-results component has one parameter called Artifact Name. Enter jboss-prod in the Artifact Name field.

Select OK.

The Application Editor now shows that the application has an application tier called Data with a referenced master component called jboss-mc-results.

If you want to edit the master component, you need to do this in from the Master Component list. (There is no button in the lower right corner where you can access the component processes.) The UI also lets you know that this is a master component because the icon is different for a normal component.

Define the application process to include a step that references the master component.

The second step prints the port number that you entered in the previous step.

Now you can deploy your application as described in Example: Deploy and troubleshoot applications.

Copy a master component to an application

When you copy a master component to an application, it becomes an application component with the same definition, processes, parameters, and properties as the master component on which it is based. After an application component is created from a master component this way, any subsequent changes to the master component will not affect the application component. Use this method when you want to use a master component just as a baseline for your application component.

This example describes how to copy a master component in an application.

Starting in the Applications list:

Select Add application.

The New Application dialog box opens.
Select Create New.
Enter the name of the new master component, select a project to which the master component belongs.

In the following example, a new application ("Your Group Summary") is created that includes a jboss-mcjc master component.
Select OK.

The Application Editor for your application opens. This is where you will author the application.

Notice that there is an undefined application tier (Tier 1) with an undefined component in it and an undefined microservice with an undefined container.
Select the button in the application tier and select Details to open the Applications Tier Details dialog box.
Change the tier name to Data in the Name field, and select OK to rename the application tier.
Select in the application tier to add a component.
Select Create from existing master component.

A list showing all available master components opens.
In the "Create a reference to a master" list, select a master component.

Select the master component called jboss-mcjc, select Use a copy, and select a project to which the master component belongs.
Select Next.

The Create from existing component dialog box opens
Change the name of the component to something that gives it more context.

After changing the component name to jboss-mcec and selecting OK, the Data tier now has a new application component called jboss-mcec, where "ec" refers to a software version:

Figure 3. Rename component
If the master component has parameters for the artifact details, modify the artifact details of the new application component and remove the parameter reference.
1. Go to the Component Details dialog box.
2. Replace the parameter ( $[artifactName] ) in the artifact details section with a specific value.
  
  In the example, replace $[artifactName] with jboss-5-maintenance, where software versions starting with lower case letters are maintenance releases
3. Click OK.
Define the application process to include a step that references the new application component.
1. The first step is defined by the jboss-mcec component and its deploy process.
  
  After you select the Deploy process, you are prompted enter to a value for the port number. Then click OK. This is the parameter that is created for the component process.
2. The second step prints the port number that you entered in the previous step. This is the resulting application process:
  
  Figure 4. Application process
Make other modifications to the application component and its component processes within application.

Now you can deploy your application as described in the Guidelines for modeling and deploying applications.

Create master components based on existing application components

Starting from the Master Components List:

Click Add +. The New dialog box opens.

Click Master component > Copy Application Component. A list of existing applications opens.

It shows the list of available applications. The default is to show the applications for all projects.

If you want to see only the applications for a specific project, select the down arrow in the All projects field to select one or more projects one of these ways:

Select the name of one or more projects.
Enter the search criteria in the Search field. The projects that match the criteria appear in the list.

You can also search for one or more applications by entering the search criteria in the Search field next to the All projects field. If there are no matches, a message appears stating that there are no applications in the selected projects.

On the left side of the dialog box, select an existing application. A list of existing components in that application appears on the right side.
Select an existing application component. The Create from existing component dialog box opens with the name of the selected component highlighted.
Change the name of the component, and enter an optional description. You can also change the project to which the master component belongs.
Select OK.

The Master Component list now includes the master component you just created.

Create master components based on existing master components

Starting from the Master components List:

Select New +.

The New dialog box opens.
Select Master component Copy Master Component.

A list of existing master components opens.
Select an existing application component.

The Create from existing component dialog box opens with the name of the selected component highlighted.
Change the name of the component, and enter an optional description.

You can also change the project to which the master component belongs.
Select OK. The Master component list now includes the new master component.