Lifecycle Scenarios

31 Lifecycle Scenarios

The best way to understand the lifecycle of artifacts and how they interact with one another is to walk through a few typical scenarios that involve versions, publishing, and managing policies for various artifacts. Each scenario revolves around a mobile app that uses a backend that has dependencies on collections and APIs.

The following scenarios should give you a sense of the interrelationships of artifacts and how dependencies can affect the lifecycle of a backend and its possible effect on an app:

Initial Deployment of a Mobile Backend

You can get a basic sense of the lifecycle flow in MCS by following the process of deploying a mobile backend that’s in a development environment to a runtime environment. We’ll use the FixItFast (FIF) example so you can see the interrelationship between the mobile backend and its associated artifacts, which consist of an API, its implementation, a connector, a user role, and a collection. You’ll see how these relationships can affect the deployment process.

In this scenario, here are the actions you’ll perform:

Resolve dependency issues that prevent you from publishing a mobile backend.
Publish a mobile backend.
Deploy the same mobile backend with all of its dependencies to another environment.

Let’s say that you’ve created a mobile backend called FIF_Customer 1.0 and you’re ready to deploy it. Before you deploy the mobile backend, let’s make a few assumptions about the artifacts that you have in the Development environment:

A mobile backend,FIF_Customer 1.0, is currently in the Draft state.
An API, FIF_IncidentReports 2.0, is published and is associated with the mobile backend.
An API implementation, incidentreports 7.0.0 , is in the Draft state.
A REST Connector API, RightNow 1.0 exists in the Draft state and is called by both versions of the API implementation.
A collection, FIF_Images 1.0 exists in the Published state and is also associated with the mobile backend.
A user role, Technician, exists and is also associated with the mobile backend.

The mobile backend is associated with the collection, the user role, and the API, which makes them dependencies of the mobile backend. The API implementation is a dependency of the API. The API implementation calls the connector, so the connector is also a dependency of the mobile backend.

Publishing the Mobile Backend

To deploy FIF_Customer 1.0 , you need to publish it first. Only published artifacts can be deployed. You select the mobile backend and click Publish. MCS performs a dependency check. The API and the collection are already published and will be picked up by the mobile backend, The API implementation and the connector are still in the Draft state and they won’t be picked up.

Note:

Some artifacts can be published with their associated artifacts. For example, if you’re publishing a mobile backend that has dependencies in the Draft state associated with it, the Confirm Publish dialog shows you the dependencies that are in Draft state and gives you the ability to publish those dependencies with the mobile backend. If you don’t want to publish a listed dependency, you’ll have to cancel the publish operation and disassociate the mobile backend from it before you can try publishing the mobile backend again. Be aware that some dependencies, like API implementations, won’t be published with the main artifact and won’t be listed in the dialog.

Here’s what you do:

Cancel the Publish operation.
Publish the API implementation and the connector API.
Publish the mobile backend.

Canceling the publish operation for the mobile backend is easy. You just click Back in the Publish dialog. Now you need to fix the dependency issues.

Publishing the Dependencies

You need to publish the API implementation and the connector. First, you’ll publish the implementation. You go to the APIs page, select FIF_IncidentReports 2.0 and open it. Next, you click on the Implementations navigation link. Although there are several version of the implementation listed, the latest version, 7.0.0, is marked as the default implementation for the API.

On the Implementations page, you select incidentreports 7.0.0 and click Publish. Once again, a dependency check is performed and it reveals that the implementation has a dependency on the RightNow connector, which is also in a Draft state. The Publish dialog tells you that you can publish the implementation along with its dependency. You know the connector has been tested and is ready to be published, so you click Publish All.

Now you can finally get back to publishing the mobile backend. On the Mobile Backends page, you select the mobile backend and click Publish. The dependency check shows no issues, so you can proceed with the publishing operation.

Deploying the Mobile Backend

On the mobile backend page, you can see that FIF_Customer 1.0 is in a Published state. Now you select the mobile backend and click Deploy. The Deployment wizard opens and you can see from the navigation links, that deployment involves these steps:

Selecting the target environment, that is, the environment to which you want to deploy the artifact.
Identifying any dependencies that could prevent the deployment.
Examining any impact that deploying the mobile backend and its dependencies could cause.
Setting some environment policies.
Deploying the artifacts.

Specify the Target Environment

The first thing you need to do is specify the target environment. The source environment is the current environment containing the mobile backend and that field is already filled in for you. You select Staging as the target environment and move on to see the list of dependencies.

Note:

The target environment must always be different from the source environment.

Reviewing Dependencies

The Dependencies page of the Deployment wizard lets you see all the artifacts the backend depends on. This can include the user realm, APIs, API implementations, connectors, collections, and roles. Each API being deployed also shows the implementation associated with it. A state of deployment is also indicated for each dependency:

Deployed indicates the dependency is already deployed.
Requires Deployment indicates the dependency will be deployed as part of the current operation.
Conflict indicates an issue exists with the dependency that affects its ability to be deployed.

You can quickly scan the page and see that all the artifacts ready to be deployed.

Assessing the Effect of the Deployment

You move on to the Impact page of the wizard. The data displayed is informational only and serves to warn you of any potential issues that might occur when the backend is deployed. For example, deploying a new version of an API implementation or a new version of a connector API might impact other mobile backends and the APIs that currently use them. There might be multiple mobile backends and APIs that call the particular API implementation or connector API.

In this scenario, no impacts are identified for your mobile backend and you can move on to the Policies page. If there had been potential issues, you’d need to assess the severity of the effects and whether you need to cancel the deployment to address the issues or proceed.

Setting the Environment Policies

Policies are specific to an environment. The policy values that affect the performance of your mobile backend in the Development environment will differ from those values in the Staging environment. You might want to apply or not apply a policy in a particular environment. You export a diff file to see what the differences are between your source environment settings and your target environment settings.

In addition to the other policies that you have to set for deployment, you also want to change the logging level value for the mobile backend. You click Edit to open an editor displaying the policies.properties file to be used in Staging. You uncomment the necessary policies along with the Logging_Level policy to include them in the target environment, save your change, and then click Import to add the policies file to the Staging environment.

Note:

Review the deployment steps for each type of artifact in Managing an Artifact’s Lifecycle to see which policies need to be set.

Completing the Deployment

Now you’re ready to complete the deployment process by moving to the confirmation page. You review the data and click Deploy. The mobile backend and its dependencies are moved to the Staging environment where they can undergo more testing before being deployed to the Production environment where they’ll be available for consumption by mobile apps.

Bug Fix

This scenario shows how you can update an API implementation and associate it with an API and add it to an already published backend.

One of the most common situations you face is when an issue in an API implementation needs to be fixed. You want to add the fixed version to the mobile backend but you have the following concerns: the mobile backend is published already so you can’t modify it and you don’t want to create a new version of it, which would force your customers to upload a whole new app due to a minor bug fix.

Note:

A key point to remember in this scenario is that you’re making a change to the API implementation. Because the custom API and the implementation are loosely coupled, you can associate the API with the newer version of the implementation, even though the API itself is in the Published state. If the published API had required a bug fix, regardless of whether the fix is a minor one or a major one, you’d have to create a new version of the API and that would mean having to create a new version of the mobile backend as well. That particular scenario is demonstrated in the New Features scenario.

In this scenario, here are the actions you’ll perform:

Make a minor change to the implementation
Create a new version of the implementation and associate it with the custom API
Publish the implementation
Deploy the mobile backend

In this scenario, you have a mobile backend, FIF_Customer 2.0, that’s in a Published state in the Development environment. It has the following dependencies:

FIF_IncidentReports 2.0 (API) in the Published state
incidentreport.js 7.0.0 (API implementation) that’s deployed to the Staging environment
RightNow 2.0 (REST Connector API) in the Published state
Realm 1.0 (the default realm) that’s deployed to the Staging environment
Customer_LC_0112 1.0 (Role) that’s deployed to the Staging environment

You need to make a small change to the API implementation. Let’s look at what you need to do to deploy the mobile backend with a new version of the API implementation:

Description of the illustration bugfix_flow.png

The following sections describes each of these steps.

Creating a New Version

There’s a minor issue with the API implementation, incidentreport.js. It updates the status of a given incident:

...
service.put(locations.apiBaseURI + 'incidents/:id/status', function(req,res) {
		var agg = {};
		agg.incidentId = req.params.id;
		var functions = [
			wrapPutOrPost(incidentOperations.updateIncident, req, agg)
		]
		async.series(functions, function(error, result){
			// we send the notification after the initial update
			notifyCustomerOfUpdate(req, agg.incidentId);
			res.end();
		 })
	});
...

but a notification isn’t sent to the customer about the update. You edit the code and save the file:

...service.put(locations.apiBaseURI + 'incidents/:id/status', function(req,res) {
		var agg = {};
		agg.incidentId = req.params.id;
		var functions = [
			wrapPutOrPost(incidentOperations.updateIncident, req, agg)
		]
		async.series(functions, function(error, result){
			// we send the notification after the initial update
			notifyCustomerOfUpdate(req, agg.incidentId);
			if (error && error != undefined){
				res.send(500, error);
			} else {
				res.send(200, result[0]);
			}
			res.end();
		 })
	});

You’ve modified the API implementation so now you need to update the version number of the implementation. The 7.0.0 version was published in our first scenario. The change that you made doesn’t affect the basic behavior of the implementation and doesn’t affect the behavior of the API, it’s a minor change. That is, this version of the implementation is backward-compatible. You need to increment the minor value of the version, so you open the manifest file, package.json, and change the version from 7.0.0 to 7.1.0 and save the file.

Uploading the Revised API Implementation

You create a new zip file containing the modified incidentreport.js and package.json files. Then you upload the new version of the implementation by selecting your API on the APIs landing page and opening it. Next, you click the Implementations navigation link. On the Implementations page, you upload the 7.1.0 version. When you upload an implementation, it automatically becomes the default implementation for the API.

On the Implementations page, you examine the dependencies for the revised implementation and verify that the implementation is associated with incidentreport 2.0 API and the RightNow 2.0 connector API. Now that you’ve associated the revised implementation with the API. Let’s see what happens if you try to deploy your mobile backend now.

Publishing the API Implementation

You go back to the Mobile Backends landing page, select FIF_Customer 2.0, and click Deploy. You set the target environment to Staging and go to the Dependencies page of the Deployment wizard. Immediately you get an error message. You see that you forgot to publish the 7.1.0 implementation. You have to cancel the deployment and go back to the Implementations page.

You open the FIF_IncidentReports 2.0 API, click the Implementations navigation link and select the incidentreport 7.1.0 implementation. From the menu above the table, you click Publish. In MCS, the API and the API implementation can be published independently of each other. This is in contrast to connectors, which are tightly coupled with their implementations, that is, when a connector API is published, its implementation is automatically published with it. Being able to publish an API implementation separately from the API gives you the versatility to associate different versions of APIs with different versions of the implementation.

Deploying the Mobile Backend

When you publish the implementation, a dependency search is performed and you see a message that there are no dependency issues. Now you can try deploying the mobile backend again. This time there are no error messages when you go back to the Mobile Backends page, select FIF_Customer 2.0, click Deploy, set your target environment, and go to the Dependencies page. The list of dependencies shows you that a few artifacts require deployment. If you proceed with the deployment, those artifacts will be deployed along with the mobile backend. You proceed to the Impact page of the wizard and see that no effects have been identified for this deployment. You can go to the Policies page.

Modifying the Environment Policies

Because you’re moving the mobile backend from the Development environment to the Staging environment, there will be a few changes that you’ll need to make to the policies file that will be used in the Staging environment. From the Policies page, you can export a diff file in which you can see the policy differences between the Development and Staging environments. You click Export and review the policies.properties file that MCS generates:

#-------------------------------------------------
#MCS Policies. Comparison of: 'dev' and'stage'
#taken at:2015-01-14 13:21:00
#-------------------------------------------------

#The value of the dev
#*.RightNow(2.0).Connector_Endpoint=http\://myexamples.com\:7001/rightnow/reports...
#The value of the dev
#*.RightNow(2.0).Routing_BindApiToImpl=RightNow(2.0)
#The value of the dev
#*.RightNow(2.0).Security_OwsmPolicy=[]
#The value of the dev
#*.fif_incidentreports(2.0).Routing_BindApiToImpl=incidentreport(7.1.0)
.
.
.

#-------------------------------------------------

The first thing you notice is that the connector endpoint needs to be updated. In the Development environment, you used a mock URL and now that the connector is moving to Staging, you need to be able to test it using an actual address. You uncomment the line

*.RightNow(2.0).Connector_Endpoint

and correct the remote URL.

Next, you check that the API is bound to the correct version of the implementation. You see that it’s set to the 7.1.0 version. Everything else in the diff file looks fine. You save your change. You also open the implementation’s manifest file by clicking the package.json tab and verify that the implementation version is correct.

Back on the Policies page of the Deployment wizard, you click Upload Policy Diff and upload your modified policies file. After that’s done, you go to the Confirmation page. You review the deployment information: name of the mobile backend, the source and target environments, the dependencies that will be deployed to the target environment, and the policy.properties file that will be applied to the target environment.

Everything looks right and you click Deploy. You see that the deployment is successful. On the Mobile Backends page, you select FIF_Customer 2.0 and see that Staging is now listed under the Deployments section and that the 7.1.0 API implementation is listed under dependencies.

The minor version change to the API implementation didn’t require a change in version for the API, or the mobile backend. The fact that the API was already published wasn’t an impediment to the deployment because the implementation could be published independently and associated with the API.

Rerouting a Mobile Backend

As you work on improving your product, you might find that you need to make some changes to it after you’ve already published your mobile backend. If the changes you want to make affect only the metadata of the mobile backend (that is, you’re making minimal changes that won’t require upgrading the mobile app that calls it), you can go ahead with those changes by rerouting the call to that mobile backend to a backend that has the updates.

You set the Routing_RouteToBackend environment policy to reroute the app’s call to the original mobile backend to a new (target) backend. The app still calls the original mobile backend but the call is redirected to a new version of the backend or to an entirely different mobile backend that incorporates the changes. The app binary doesn’t need to be recompiled because the app isn’t directly associated with the new mobile backend. The app calls the original backend so there’s no change to the client ID and client secret.

In this scenario, you’ll see how to redirect calls to a mobile backend. Let’s say you need to change the permissions for a storage collection. The app calls the mobile backend, FIF_Customer 4.1 which is already published and deployed to a runtime environment called Production.

Assume you have the following setup:

FIF_Customer 4.1
FIF_IncidentReports 2.0API
incidentreports.js 7.2.0 API implementation
FIF_Parts 1.0 storage collection
RightNow 2.0 REST Connector API
Realm 1.1

All artifacts are published and deployed to a runtime environment.

Updating the Collection and Rerouting the Call to the Mobile Backend

You have a collection, FIF_Parts 1.0 which stores the images and serial numbers for various parts used to fix appliances. You defined the collection to have a Shared collection type. You’ve set Read-Only access permission to the Sales Representative role and Read-Write to the Engineer role and associated it FIF_Customer 4.1 when the mobile backend was still in Draft state.

FiF_Customer 4.1 has been published and you realize you forgot to give Read-Write permission to the Parts Manager role and FIF_Parts 1.0 is published.

Here’s how you can add the Parts Manager role to the Read-Write permission list and get it associated with a mobile backend that your app can call (without having to recompile your app):

Create a new version of the FIF_Parts 1.0 collection, and call it FIF_Parts 1.5.
Set the access permissions for FIF_Parts 1.5 just like you did for version 1.0 but this time make sure to add the Parts Manager role to the Read-Write permission list.
Save the collection.
Create a new version of the mobile backend, call it FIF_Customer 4.5.

The new 4.5 version of the backend will have all the artifact associations of the 4.1 version.
On the mobile backend landing page, open FIF_Customer 4.5 , go to the Storage page and disassociate it from the old FIF_Parts 1.0 and select FIF_Parts 1.5.
After thorough testing, publish FIF_Customer 4.5. The publishing process lets you publish any unpublished dependencies at the same time.
Deploy the mobile backend to the Production environment, reviewing and resolving any effects the deployment could have on other artifacts, and edit the routing policy:

FIF_Customer(4.1).*.Routing_RouteToBackend=FIF_Customer(4.5)

When your app calls the mobile backend, it’s redirected to the new version of the mobile backend that has the updated collection.

New Features

As you work on improving your product, at some point you’re going to add at least one new major feature or make a major change to a feature. A major change will affect the mobile backend, requiring you to create a new version that won’t be backward-compatible with previous versions. Changes could consist of adding another dependency or making a major change to the mobile backend or one of its dependencies. This time, deploying your mobile backend will mean that any mobile apps calling on the mobile backend will require that customer upgrade the application.

In this scenario, you introduce a new feature to your FIF_Customer 2.1 mobile backend. Let’s assume you have the following artifacts:

FIF_Customer 2.1 mobile backend already deployed to the Production environment
FIF_IncidentReports 2.0 API
incidentreports.js 7.2.0 API implementation
FIF_Images 1.0 storage collection
RightNow 2.0 REST Connector API
Realm 1.0
Customer_LC_0112 1.0 user role

Upgrading the Mobile Backend

You’ve been using FIF_IncidentReports 2.1 and now you’ve got a new and improved version of it that you want the mobile backend to use. You’ve created a 3.0 version of it that will improve how the incident report data is obtained and you want to make it available to the mobile app. The change in the major value of the version number implies that the functionality of the API isn’t backward-compatible. The major change in the API necessitates creating a new version of the API implementation, which could affect any connector APIs that it calls, and definitely means that a new version of the mobile backend is needed.

Here’s what you’ll need to do to add a new major feature:

Create a new major version of the API.
Create a new major version of the API implementation for the new API.
Test the API and the new implementation.
If necessary, create a new major or minor version of the connector API and test it also.
Create a new major version of the mobile backend by selecting the not backward-compatible option, which automatically increments the major version value. (In this scenario, the version will change from 2.1 to 3.0.)
Select the new 3.0 version of the mobile backend, open it, and click the APIs navigation link. You click X to remove the association with the old 2.0 version of the API and click Select APIs to associate the new 3.0 version of the API.

Note:
You don’t need to define new user roles, a new collection, or a realm but you will have to associate the roles and the collection with the new version of the mobile backend.
Publish the mobile backend after you’ve thoroughly tested all the components. The publishing process lets you publish all the dependencies at the same time.
Deploy the mobile backend to Staging, reviewing and resolving any effects the deployment could have on other artifacts, and modifying environment policies as needed.

The mobile apps that use FIF_Customer will have to upgrade to use the new version of the mobile backend. Later on, you decide that it isn’t necessary to have a running 2.1 version because all the mobile apps have been upgraded to use the new version. You select the FIF_Customer 2.1 mobile backend from the Mobile Backends page, and select More > Manage Activation. In the Manage Activation dialog, you change the state of the mobile backend to inactive. A mobile backend that’s in the inactive state can’t accept requests from mobile apps. The activation state is specific to an environment, so if you’ve deployed version 2.1 to Staging and then to Production, you’ll need to change its activation state for each environment.