Understanding Lifecycles

4 Understanding Lifecycles

Oracle Mobile Cloud Enterprise provides a UI to simplify lifecycle management of your artifacts. As OMCe administrator, you use these features to create, maintain and publish backends, APIs and other artifacts.

An important part of your role as OMCe administrator is managing artifacts from implementation to production and maintaining them through multiple versions, also known as lifecycle.

The artifacts you’ll be working with most often are clients, backends, custom APIs, connector APIs, and collections. In general, the same lifecycle phases apply to all of these artifacts.

Throughout the development and testing phases of a project, artifacts can be created and edited in a Draft state, then Published (or moved to the trash). All artifacts are automatically assigned a version of 1.0 when they’re created. During an artifact’s lifecycle, new versions can be created and updated. Since artifacts are closely related to each other, it’s important to keep track of dependencies and manage interactions.

This chapter introduces these important lifecycle phases and explains how you can work with an artifact through each of the phases and manage interactions between associated artifacts.

Draft State

When you create an artifact, whether it’s a client, a collection, a custom API or any other type, the artifact has a Draft status. With a Draft version of an artifact, you can edit, create a new version, update an existing version, or remove the artifact (move it to the trash).

While an artifact is in the Draft state, you can experiment with it, modify it as many times as you need to, and test it thoroughly. You publish the artifact when you’re satisfied with its configuration.

Description of lifecycle_phase1a_ext.png follows

Description of the illustration lifecycle_phase1a_ext.png

You can update the version number of an artifact in Draft state or create a new version to modify, then you can publish the updated artifact or the new version of the artifact.

Published State

When a specific version of an artifact is final, you can publish it. After it’s published, that version of the artifact can no longer be edited. If you create a new version of an artifact that’s in a Draft or Published state, the new version is created in the Draft state.

If there are no dependency issues, a published artifact can be exported to another instance. If you need to modify the artifact, you can create a new version of it and modify the new version. Because the new version is in the Draft state, you’ll need to publish it before you can export it.

You can have multiple versions of an artifact. You can export different versions of an artifact to different instances.

If you’ve published an artifact by mistake or realize after it’s been published that you need to make a change, you can create a new version of the artifact and make your changes to it. When you’re satisfied with the configuration of the new version, you can publish it. For API implementations, OMCe automatically makes the latest version the default when the implementation is initially loaded. If the most recent version loaded isn’t the implementation that you want associated with your API, you must explicitly specify a previously loaded implementation as the default.

You have the choice of keeping the previous version of an artifact as long as it’s needed, or moving it to the trash (removing the artifact from the main view). In the case of a backend, you also have the option of changing its activation state to inactive. Artifacts in the trash are still accessible at runtime. For example, if you have a backend that calls My_API and someone moves My_API to the trash, the app can still call the backend and My_API.

All artifacts can be published independently and some can also be published when you publish their associated artifacts. For example, you can publish an API independently or the API can be published when you publish its associated backend.

When you publish an artifact, it’s checked for any dependencies and whether or not those dependencies are already published. You'll be able to see the list of dependencies and can decide whether or not to proceed with publishing. If you decide to publish, any unpublished dependencies may be published too.

This table compares the Draft and Published states, behavior, and dependency considerations for backends, collections, custom APIs, and connector APIs:

Artifact Type	Permissible in Draft state	Permissible in Published state	Number of active versions per instance	Dependencies
Backend	Edit Create new version Update version Publish Export/import Manage activation Move to Trash	Create new version Manage activation Move to Trash	Multiple	Collection Custom APIs Connector APIs Roles
Collection	Edit Associate a backend Create new version Update version Publish Export/import Move to Trash	Create new version Move to Trash	Multiple	Roles
Custom API	Edit Create new version Update version Publish Export/import Move to Trash	Create new version Move to Trash	Multiple (Note: Only one API version per backend version)	Roles, Connector APIs, Custom APIs
Connector	Edit Create new version Update version Publish Export/import Move to Trash	Create new version Move to Trash	Multiple	None

Making Changes After a Backend is Published (Rerouting)

If you need to make backend fixes to your app, but the app’s backend is already in production, there is a way that you can incorporate those changes into your app without having to recompile it — reroute the call to the backend.

Using a policy, you can reroute the call your app makes to the backend to a different backend that contains the needed fixes. First, publish the backend that contains the fix. Then, set the Routing_RouteToBackend policy, which lets you specify the original backend and redirect the call to the target backend with the fixes. Because your app is calling the original backend, there's no change to the ClientID or ClientSecret, which would require you to recompile the app binary.

Rerouting the call to a backend is useful when you want to make a minor fix that requires a change to the backend’s metadata. Some instances where rerouting a published backend is useful:

Making modifications to an API or a connector, such as adding an endpoint that you forgot.
Changing the access permissions for an API.
Changing the access permissions for a storage collection.
Changing the offline sync property of a storage collection.
Adding a storage collection to a backend, such as when you want to include a more efficient API implementation that needs storage for caching purposes.
You have a change to the backend and you want to distribute the backend that has the fixes to other instances.

Note:

The Routing_RouteToBackend policy should also be set when you’re exporting or importing a package containing the target backend.

You can set Routing_RouteToBackend to specify that any API calls within the context of any version of the original backend are routed to the target backend:

OriginalBackend.*.Routing_RouteToBackend=TargetBackend(X.X)
OriginalBackend(A.A).*.Routing_RouteToBackend=TargetBackend(X.X)

For example: FiF_Customer.*.Routing_RouteToBackend=FiF_Customer(3.2)

Any API calls sent to any version of FiF_Customer are sent to FiF_Customer, v3.2.

Note:

You can’t use wildcards (*) in version values when setting the Routing_RouteToBackend policy.

You can also specify a particular version of the backend to route to a specific version of it. For example: FiF_Customer(1.3).*.Routing_RouteToBackend=FiF_Customer(3.5)

Any API calls sent to FiF_Customer, v1.3 are sent to FiF_Customer, v3.5.

Note:

If more than one redirect policy is defined for the backend, the policy defined with the fully-qualified backend takes precedence.

A call can be redirected to any backend, not just another version of the same backend. For example: FiF_Customer(1.3).*.Routing_RouteToBackend=RepairIt(1.0)

Any API calls to FiF_Customer, v1.3 are sent to the backend RepairIt, v1.0.

You can also create a chain of rerouted calls to a backend. For example, a call to backend_A can be rerouted to backend_B. A second routing policy could redirect any calls to backend_B to backend_C. This would result in a call to backend_A being redirected to backend_C.

Packaging a Rerouted Backend

If you are exporting or importing a backend that is being rerouted, the Dependencies page includes a "Redirect to" statement that specifies the immediate target backend. Using the previous example, if a rerouting chain exists, and backend_A is being exported, the Dependencies page indicates a reroute to backend_B. Also, the policies.properties file lists only the routing policy for the backend in the package (backend_A).

Conditions for Rerouting a Backend

The following conditions apply whenever you reroute a backend:

The original backend can be in an inactive state and be rerouted.
If the app calls the original backend, notifications are sent and devices are registered using the client credentials associated with the original backend. However, if the app calls the target backend directly, then the clients from the target backend are used to send the notifications and register devices.
If Social Identity is used to access an API and its associated backend is rerouted, the social authentication provider of the target backend should be selected and the access token from that provider should be entered in the Authentication section of the API Test page.
If the original backend is exported, the target backend is not considered to be a dependency of the original.
Generally, if either the original or target backend is included in an export or import package, the routing policy should be set when the export package is created or when the contents of the package are imported.
When a backend is rerouted, the system log records the event. You can see which backends are being redirected from the log messages.

Versioning

Each time you create an artifact, it’s assigned a version value of 1.0. As long as the artifact is in a Draft state, you can edit it, update its version, or create a new version (a major or minor incremental increase). As you develop your artifact, you can change the version's major and minor values (Major.minor).

When the major version number increments from 3.5 to 4.0 or even 6.0, it indicates that a significant change has been made to the current instance of the artifact, which likely affects its relationship to related artifacts. For example, changing the Web Services Description Language (WSDL) file of a SOAP Connector API would necessitate creating a new custom API implementation for it. A major change to a backend would also necessitate upgrading any mobile apps that use it.

After you create an artifact and it’s still in a Draft state, you can change the version number with the Update Version Number command available from the landing page for your artifact type. For example, to update the version number for a backend, you can go to the Backends page and select your backend, select More > Update Version and change the version number.

App Profile Versions

An app profile represents a specific version of a mobile app binary and the version number you assign to the app profile should correspond to the mobile app binary that it represents. When you create an app profile, you enter the version in the same format as the app binary. For example, if the app has a version of 3.1.2.3, the version you enter for the app profile is 3.1.2.3. No default version is applied to a new app profile.

While the app profile is in Draft state, you can update the version. For instance if the app version changes, you can change the version by opening the app profile and editing the Version field. After the app profile is published, you can create a new version through the More > New Version command on the App Profiles page.

Deleting an Artifact

Deleting an artifact permanently takes two steps. When you have an artifact that you don't need anymore, you can move it to the trash where it's kept until you're sure you want to delete. To delete an artifact permanently, you purge the artifact from the trash.

You can move an artifact that’s in Draft or Published state to the trash. Depending on whether or not it’s needed later, you can restore it or purge it.

Almost any artifact can be moved to the trash. For details on the conditions for removing artifacts, see Moving an Artifact to the Trash.

When you restore an artifact, it retains the same state it had when it was moved to the trash. For details on restoration, see Restoring an Artifact.

Purging is a permanent deletion and is available only from the Administration view. For details on how to permanently delete an artifact, see Purging an Artifact.

Moving an Artifact to the Trash

Putting an artifact in the trash is considered a temporary deletion, the artifact is removed from the main view and is inaccessible to other artifacts. You can move an artifact that’s in Draft or Published state to the trash. Depending on whether or not it’s needed later, you can restore it or purge it.

You can’t use artifacts that are in the trash because they can’t be accessed, called, or executed. If you change your mind later or find you do need an artifact in the trash, you can restore it depending on the deletion policies.

The Asset_AllowTrash and Asset_AllowUntrash policies control the ability to move an artifact to the trash or restore it. You can set these policies to one of the following values:

All
None
Draft
Published

For details on setting policies, see Policies.

While it’s in the trash, an artifact in Draft state can’t be published, and any dependencies of that artifact can’t be published regardless of whether or not those dependencies are in the trash. If you restore it, an artifact in Draft state can then be published.

Note:

When an artifact is removed, its associated policies are removed along with the artifact and its dependencies. If the artifact is restored, the policies are also restored.

Upstream and Downstream Dependencies

You can move an artifact that's in Draft or Published state to the trash, but there are some conditions based on whether dependencies are involved. An artifact that’s called by another artifact has an upstream dependency. An artifact that calls another artifact has a downstream dependency. If an artifact has dependencies that are active (not in the trash), you need to resolve the relationships to those dependencies before you can move the artifact to the trash.

Description of trash_dependencies.png follows

Description of the illustration trash_dependencies.png

For example, say you created an API called MyAPI. The backend that calls it, MyBackend, is the upstream dependency ofMyAPI. The API calls its implementation, MyAPIImpl, is the downstream dependency of MyAPI.

Below are the common dependency scenarios that affect whether or not you can move an artifact to the trash, and whether or not dependencies of that artifact are also moved to the trash:

Case 1, Artifact is a dependency of a published artifact: If the artifact you want to remove is a dependency of a published artifact, you can't move the artifact in question to the trash because it would break its relationship with the published artifact. If you need to move the artifact to the trash, you must break the relationship between the artifacts first. For example, you want to move MyAPI to the trash but you can’t because it’s a dependency of MyBackend, which is published. You have to break the relationship by moving MyBackend to the trash first, then moving MyAPI to the trash. If you need MyBackend, you can create a new version of it before moving the previous version to the trash.

Case 2, Artifact has tightly-coupled dependencies: If the artifact you want to remove has tightly coupled dependencies, moving it to the trash will remove the artifact with its dependencies. For example, if you need to remove an API that’s associated with a real implementation or a connector API and its implementation, moving the API to the trash will also remove the implementation. (If the API is associated with a mock implementation, the relationship is broken and only the API is moved to the trash.)

Case 3, Artifact has dependencies: If the artifact that you want to move to the trash has dependencies that aren’t tightly coupled, you must disassociate the artifact from its dependencies before you can move it to the trash. Only first-level upstream and downstream dependencies are considered. If there are any second-level dependencies (for example, the API’s implementation calls a connector), you’ll have to be aware of those relationships and resolve them prior to moving the artifact to the trash.

If the artifact has a dependency on a role, the artifact can be moved to the trash but not the role. Rule of thumb: Roles can’t be trashed.

The following table lists the dependencies involved in a move to the trash. For each artifact type, it lists 1) the dependencies that are moved to the trash with the artifact, 2) the possible dependencies that may be associated with the artifact but are not moved to the trash with the artifact, 3) and any published upstream dependencies that would prevent a move to the trash.

Table 4-1 Dependencies Involved in a Move to the Trash

Artifact	Dependencies Moved to the Trash	Dependencies Not Moved to the Trash	Published Upstream Dependency That Prevents a Move to the Trash
Client	None	Backend App Profile	None
Backend	None	APIs Collections	Client
API	API Implementation Note: mock implementations can’t be moved to Trash.	Backend API implementations that invoke the API Roles – Any role associated with the API is revoked. Roles can’t be moved to Trash.	Backend
API Implementation	None	API that is implemented APIs that are called by the implementation	API that lists the implementation as active
Collection	None	Backend Roles – Any role associated with the collection is revoked. Roles can’t be moved to Trash.	Backend
Connector	None	Backend API implementations that call the connector.	None

Restoring an Artifact

You might find that you need an artifact that’s been moved to the trash. Restored artifacts retain the same state they had when they were moved to the trash. That is, an artifact in Draft state that was moved to the trash will still be in Draft state when restored.

As with moving an artifact to the trash, restoring an artifact has some considerations:

If the artifact has no naming or version conflict, you can restore it by simply clicking the Trash () and selecting Restore from Trash from the Trash drawer () and confirming the restoration action.

Description of the illustration restore_realm.png
If duplicate artifacts exist (that is, artifacts with the same name and version) and one of these artifacts is in the trash, you can’t restore the artifact. You must resolve the conflict first in one of the following ways and then restore the artifact:
- Move the active artifact to the trash and restore the one already in the trash.
- Change the version of the active artifact and then restore the one in the trash.

The following table lists the types of artifacts that can be restored and which dependencies are restored from the trash with each type of artifact. The last column lists the possible upstream and downstream dependencies of the artifact that are not in the trash and that could be affected by the restoration. These items are displayed in the Restore dialog as information only.

Artifact	Dependencies Restored With Artifact	Possible Artifact Dependencies Not in the Trash
Client	None	Backend
Backend	None	APIs Collections
API	Role	Backend API Implementation (non-mock) API implementation that calls the API
API Implementation	None	API that is implemented
Collection	Role	Backend
Connector	None	Backend

Detailed instructions for restoring an artifact in the trash are included for each artifact type in the chapters that follow.

Restoring an Artifact from Administration

You can restore an artifact from the Trash menu as described above, or you can restore deleted artifacts from the Administration view.

Click and select Settings from the side menu.
Click Deleted Artifacts.
Filter the list by selecting the type of artifacts you want to see. The default value is All Artifacts.
You can also use the Filter field to further refine the list:
- By the name of the artifact.
- By version number.
- By the name of the person who moved the artifact to the trash.
Description of the illustration admin_restore.png
Click the checkbox for each artifact you want to restore and click Restore.

To select all the items in the table at once, click the checkbox next to Artifact in the table header. Click again to clear all selections.

Artifact selection isn’t persistent across pages. You can restore only the selected artifacts on the current page. If you want to restore artifacts listed across multiple pages, you’ll have to restore the artifacts on the current page and then go to the next page.

Purging an Artifact

So how do you permanently delete an artifact? You must be a mobile cloud administrator and you purge it via the Deleted Artifacts tab from the Administration view. When an artifact is purged, it no longer appears in the list of trashed items and can’t be restored.

Just as dependencies can affect restoring an artifact, they affect purging an artifact from the trash. If the artifact you want to purge has downstream dependencies, those dependencies are deleted along with the artifact. For example, when you purge an API in the trash, its implementation is deleted as well.

If the artifact is a downstream dependency of another artifact, you need to resolve the dependency with the other artifact before you can purge it.

The following table shows you which dependencies will be purged with a each type of artifact.

Artifact Type	Dependencies Purged with the Artifact	Dependencies Not Purged with the Artifact
Backend	None	APIs Collections
API	API implementations Roles	Backends Mock API Implementations
API Implementation	None	API implemented by the implementation
Connector	None	Backends
Collection	Roles	Backends API implementations that call the connector

Purging Artifacts from Administration

To permanently remove an artifact, you need to purge it from the trash. You can only purge artifacts from the Administration view.

Click and select Settings from the side menu.
Click Deleted Artifacts.

By default, the list shows all artifacts in the trash. Artifacts are displayed in a descending order of when items were moved to the trash. You can change the display to list artifacts in alphabetical order of the person who moved the artifacts to the trash or by comments.
Filter the list by selecting the type of artifacts you want to see. The default value is All Artifacts.
You can also use the Filter field to further refine the list:
- By the name of the artifact.
- By version number.
- By the name of the team member who moved the artifact to the trash.
You can also sort the order of the items in the trash by artifact, type, time the item was moved to the trash, or by the person who moved the item to the trash.

Description of the illustration admin_purge.png
Click the checkbox of each artifact that you want to purge and click Purge.

To select all the items in the table at once, click the checkbox next to Artifact in the table header. Click again to clear all selections.

Artifact selection isn’t persistent across pages. You can purge only the selected artifacts on the current page. If you want to purge artifacts listed across multiple pages, purge the artifacts on the current page and then go to the next page.

Artifact Lifecycles

Clients, backends, APIs, and other artifacts in OMCe each have an independent lifecycle.

In most respects, how an artifact is managed after it’s created is the same regardless of whether it’s a client, backend, collection, connector API, or a custom API. You‘ve learned how to create an artifact, then modify it, and test it. Now that you have a viable artifact, it’s time to publish it, perhaps create new versions or update existing versions and eventually deploy it to another environment for others to test and use.

There are some key details unique to different types of artifacts. The following chapters show you how to take each type of artifact through its lifecycle phases: