Publishing Initiatives to the Workspaces

About Workspaces

Workspace is an interface that enables Solution Designer to interact with the DevOps engine and generates the requested cartridge. The DevOps engine has all the plug-ins required by Solution Designer to build the requested cartridge. You can then deploy the cartridge into UIM. A cartridge is a collection of PSR models which includes specifications, characteristics, design parameters, parameter mappings, design policies, and delivery policies that are defined in Solution Designer. The artifacts are compiled into a deployable JAR file.

Workspaces are created during the Solution Designer installation. You can't create, modify, or update the workspaces in Solution Designer. The following workspaces are available in Solution Designer:

Non-production or Test workspace: A workspace where the initiatives are published to the test instance and the test cartridges are generated. These cartridges are deployed in the UIM run-time instances and you can do the functional testing. Based on the functional testing results, you can modify the initiative contents and then perform acceptance testing. The modified initiatives are published again to the test workspace until the initiative content is finalized and passes acceptance testing.
Production workspace: A workspace where the initiatives are published and the production cartridges are generated. After the initiative is released to the production workspace, the DevOps engine generates a production cartridge which in turn is deployed to the UIM run-time instance.

Cartridge Generation Process

You publish an initiative to a test or production workspace. The workspace interacts with UIM Participant. UIM Participant is a micro-service that participates in the workspace operation Publish. The UIM participant in turn interacts with the DevOps engine to generate the requested cartridges. After generating the cartridge, the DevOps engine informs the UIM participant and the UIM participant informs the workspace about the status of the request. The location of the generated cartridge artifacts and the location of the cartridge workspace that can be deployed in Design Studio are displayed in the workspace. You can download these cartridge artifacts and deploy them in UIM. See "Deploying Cartridges" in UIM Cartridge Guide for more information on deploying cartridges in UIM. You can download the cartridge workspace and import it into the Design Studio Eclipse environment to code the design and assign logic for advanced policies, define parameters mapping, define logic for design action mapping, define logic for delivery action mapping, and build solution cartridges for OSM and ASAP.

The generated cartridge workspace contains a base class and an extended designer class. A base class is the Java code that the DevOps engine generated to implement the behavior of the specifications and must not be modified. An extended designer class is the Java code which lets you write your custom code for the extension points that are provided in the class. You can do the following in extended designer class:

Coding the design and assign policies according to your business requirements using advanced policies
Debugging the existing design and assign policies for any errors including compilation errors

After you complete coding, you can place the extended designer class in the S3-compatible object storage. Enter the object storage's relative path in the Advanced policy implementation assets section in the General Information tab of a specification. Publish the initiative and the DevOps engine builds the requested cartridge that you can deploy to a run-time environment. See "Extending Solution Designer" in Developer's Guide for more information on extended designer class.

You can download the cartridge workspace and import it into the Design Studio Eclipse environment to build solution cartridges for OSM and ASAP. You can do the following in Design Studio:

Modeling ASAP with the ASDLs and CSDLs generated in the cartridge for the activation system
Modeling OSM with the Action Parameter Bindings generated in the cartridge

Then you can build and package the cartridge in Design Studio and then deploy it to a run-time environment.

Viewing Workspaces

You must have the service catalog admin role to view the workspaces and manage the connection for the workspaces.

To view the workspace:

In the Solution Designer landing page, click the application that you want to work with.
In the Workspaces application, click the Test or Production workspace.

The workspace details page opens.
The following tabs are displayed:
- The Operations tab lists all the initiatives that are published for the selected workspace.
- The Participants tab lists the participants that are defined for the selected workspace. UIM Participant is the only participant listed. You can't delete the UIM Participant and you cannot define any new participants.
You can view the tasks for the published initiative in the Operations tab:
1. In the Operations tab, click the ID for the published initiative.
  
  The Tasks page opens.
  
  The Prepare task prepares the transaction for the UIM Participant and generates the cartridge. If the transaction fails, the Prepare task fails.
  
  The Commit task commits the transaction. It runs automatically and completes successfully whenever the Prepare task is completed.
2. Click View Operation to view the task details.
  
  The Task Details drawer appears.
3. The Task Details drawer displays the location of the cartridge and the cartridge workspace in the Operation Task Message for the completed task. If the task fails, the Task Details drawer displays an appropriate message.
4. Close the Task Details drawer and click the left arrow to go to the operations details page.
You can view the defined participants in the Participants tab.
Click Go to Workspaces to return to the Workspaces page.

Managing Connections

You must have Service Catalog Admin user role to manage the connections. Connections specify the details of the applications to which the workspaces connect to perform an action.

You can perform the following tasks in the Connections page:

Creating New Connections

You must have the service catalog admin user role to create new connections. After you install Solution Designer, you must manually create a connection for the workspaces to publish the initiative content.

To create a new connection:

Create an initiative exclusively for creating the connections without any initiative items in it. For example, create an initiative with the name Connection. See "Creating Initiatives" for more details on how to create an initiative.
In the Workspaces application, click Manage Connections.

A Connections page opens which lists the available connections.
Click New Connection.

A New Connection page opens.

Enter the following details:

Table 7-1 New Connection details

Name	Required or optional	Description
Name	Required	Name of the connection.
Initiative	Required	Select the initiative that was created exclusively for connections. For example, Connection.
Authentication	Required	Provide authentication details to authenticate the UIM Participant. Enter the ID, Secret, and Token Endpoint URL for the UIM Participant image.
Participant	Required	Add the Participant details. Select the participant ID (UIM), workspace ( Test or Production), Scope (/lcm) and the end point URL for the UIM participant (http://uim-participant:8080). You must add two UIM participants one each for the Test and Production workspaces.

Click Create.

The connection is created and is listed in the Connections page.
Navigate to the Connection Initiative and transition the initiative to Acceptance Testing phase.
Publish the initiative to the Test workspace. You must wait until the publishing status changes to Up to Date. See "Publishing Initiatives to the Test Workspace" for more information on publishing initiatives to the Test workspace.
Publish the initiative to the Production workspace. Wait until the initiative's status transitions to Released. This makes the connection available for the Publish operation of other initiatives. See "Publishing Initiatives to the Production Workspace" for more information on publishing initiatives to the Production workspace.

Updating Connections

You must have Service Catalog Admin user role to update the connection details. You may want to update an existing connection to add or update the participant details or to update the authentication details.

To update a connection:

In the Solution Designer landing page, click the Workspaces application.
In the Workspaces application, click Manage Connections.

The Connections page opens.
Search and select the connection that you want to update.

The connection details page opens.
Update the name, the authentication details, and the participant details.
Click Save.

The updated connection details are saved.

Deleting Connections

You must have service catalog admin use role to delete a connection.

To delete a connection:

In the Solution Designer landing page, click the Workspaces application.
In the Workspaces application, click Manage Connections.

The Connections page opens.
Search for an existing connection and click Delete.

A confirmation dialog box appears.
Click Delete in the confirmation dialog box.

The connection is deleted.

Publishing Initiatives to the Test Workspace

You must have the service catalog administrator role to publish the initiatives. After you complete defining the PSR models and their contents, you transition the initiative from the Definition phase to the Functional Testing phase. After the approver approves the initiative to start functional testing, you can publish the initiative to the Test workspace to generate a cartridge. See "Lifecycle of Initiatives" for more details on various statuses of initiatives.

To publish an initiative to the Test workspace:

In the Solution Designer landing page, click the Initiatives application.
In the Initiatives application, search for the initiative and click to open it.

The initiative details page opens.
Click the Publishing tab.

The Publishing details page opens. You see a row with the name Test which indicates the Test workspace.
Click Publish in the Actions column.

Note:
You will see Publish only when the initiative is approved for functional testing, in acceptance testing phase, and before the initiative is approved for rollout. See "Lifecycle of Initiatives" for more details on various phases of initiatives.

The publishing status transitions from Never published to In Progress.

You must wait until you receive a pop-up message Publish successful to workspace Test. The status changes to Up to Date.

Note:
If the publish operation fails, the status changes to Failed and you can view the error message in the workspace.
You can download the cartridge artifacts, cartridge workspace or view the error message by clicking the Edit Workspace in the Actions column.

The Test workspace details page opens.
In the Operations tab, locate the initiative that you published. The status of the Publish operation is Complete or Failed in the workspace.
Click the ID link that corresponds to your initiative.

The Tasks page opens. See "Viewing Workspaces" for more details on viewing workspaces.
Click View Operation in the Commit row or in the Prepare row.

The Task Details drawer opens.
You see the following in the Task Details:
- If the Publish operation is completed, the location of the cartridge artifacts and the location of the cartridge workspace for the initiative is provided. For example,
```
Operation Task Message
Cartridge artifacts for Mobile initiative is available at
        http://scdapplication:9999/workspaceOperations/v1/publishOperations/10005/artifacts/cartridges
Cartridge workspace for Mobile initiative is available at
        http://scdapplication:9999/workspaceOperations/v1/publishOperations/10005/artifacts/workspace
```
  You can copy the location and paste it in a web browser to download the cartridge artifacts and deploy it in the UIM run-time environment. You can perform the functional testing and acceptance testing using this generated cartridge.
- If the Publish operation is failed, an appropriate error message is displayed with the error code.
  
  You can also download the cartridge workspace. To implement custom code for various extension points, you can download the cartridge workspace which contains the Design Studio projects and import them to Design Studio Eclipse workspace. The cartridge workspace contains base class and an extended designer class. You can code the custom implementation in the extended designer class, and place it in the S3-compatible object storage. See "Extending Solution Designer" in Developer's Guide. Enter the relative path of the object storage location in the specification in the Advanced policy implementation assets section. The DevOps engine builds the cartridge with the base code and also the implementation code in the extended designer class from the link provided in the Advanced policy implementation assets section.
  After you correct the errors, you can republish the initiative and follow the steps 1 to 9. You can download the cartridge artifacts on a successful publish operation to deploy it in the run-time environment.
Note:
If the functional testing or acceptance testing uncovers any issues, you update the initiative contents accordingly and republish the initiative to the Test Workspace. You can publish the initiative multiple times to the Test workspace until your testing is successful.

Publishing Initiatives to the Production Workspace

You must have Service Catalog Admin user role to publish initiatives to the Production workspace.

To publish an initiative to the Production workspace:

In the Solution Designer landing page, click the Initiatives application.
In the Initiatives application, search for the initiative and click to open it.

The initiative details page opens.
In the Lifecycle tab, click Release Initiative.

The initiative's content is automatically published to the Production workspace.
After the requested cartridge is generated successfully in the Production workspace, the initiative's status transitions to Released.

If there is an error in the Publish operation, the initiative's status remains in Approval status. Release Initiative is enabled to republish the initiative to the Production workspace.
You can download the cartridge or view the error message in the Workspaces application.
To download the cartridge or view the error in Production workspace:
1. In the Workspaces application, click the Production workspace.
  
  The Production workspace details page opens.
2. In the Operations tab, locate the initiative that you published. The status of the publish operation is Complete or Failed.
3. Click the ID link that corresponds to your initiative.
  
  The Tasks page opens. See "Viewing Workspaces" for more details on workspaces.
4. Click View Operation in the Commit row or in the Prepare row.
  
  The Task Details drawer opens.
5. You see the following in the Task Details:
  - If the Publish operation is completed, the location of the cartridge artifacts and the location of the cartridge workspace for the initiative are provided. For example,
```
Operation Task Message
Cartridge artifacts for Mobile initiative is available at
        http://scdapplication:9999/workspaceOperations/v1/publishOperations/10005/artifacts/cartridges
Cartridge workspace for Mobile initiative is available at
        http://scdapplication:9999/workspaceOperations/v1/publishOperations/10005/artifacts/workspace
```
    You can copy the location of the cartridge artifacts and paste it in a web browser to download the cartridge and deploy it in UIM run-time production environment. The initiative contents are live in the run-time environment.
    You can paste the location of the cartridge workspace in a web browser to download the Design Studio project. You can import this project into Design Studio Eclipse environment and update based on your business use case.
  - If the Publish operation is failed, an appropriate error message is displayed with the error code.
    
    After you correct the errors, you can release the initiative again in the initiatives application by following the steps from 2 to 6.

Troubleshooting Issues

This section describes how to troubleshoot issues that you may experience when publishing an initiative.

Configuration Issues

The publish operation of an initiative may fail if the participants are not configured properly. To verify if the connections are set up correctly, see "Creating New Connections".

The configuration issues may occur in one of the following:

Incorrect participant information for the connections in the workspace.
Incorrect UIM Participant deployment configuration.

After you correct the configuration issues, the publish operation mostly succeeds.

Validation Errors

After you fix the configuration issues, the publish operation may fail due to validation errors.

When there are validation errors for the specifications or the PSR Models, error markers appear during transitioning the initiative. You can view the validation errors in the Initiatives Items tab in the initiatives editor page and in the specifications results page in the Specifications application and fix those errors. After fixing all the validation errors, republish the initiative to the test workspace.

Other Errors

After you fix all the validation errors and have a proper configuration of the UIM participant, the publish operation may fail due to downstream UIM participant issues. You can check the failure reason by navigating to Task Details drawer in the Tasks page in the Workspaces application. See "Publishing Initiatives to the Test Workspace" for more details. You can view the reason, fix the issue, and republish the initiative.

If the failure reason is unclear from the Workspaces application, you can contact your system administrator to view the logs for the UIM participant, headless design studio, or workspace manager for the detailed failure reason. You can fix those issues and republish the initiative.