4 Understanding Lifecycles
Oracle Autonomous Mobile Cloud Enterprise provides a UI to simplify lifecycle management of your artifacts. As AMCe administrator, you use these features to create, maintain and publish backends, APIs and other artifacts.
An important part of your role as AMCe 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.
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, AMCe 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:
TheRouting_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 theRouting_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.
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.
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.
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.
-
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.
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 |
Artifact Lifecycles
Clients, backends, APIs, and other artifacts in AMCe 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: