Managing an Artifact’s Lifecycle

32 Managing an Artifact’s Lifecycle

Mobile backends, APIs, and other artifacts in Oracle Mobile Cloud Service (MCS) each have an independent lifecycle. As a mobile cloud administrator, you can manage the versioning, deployment, and dependency management of each.

In most respects, how an artifact is managed after it’s created is the same regardless of whether it’s a client, mobile 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.

We'll show you how to take each of these artifacts through its lifecycle phases:

Note:

Remember, to perform operations on artifacts, such as viewing, creating new versions, editing, and so on in an environment, you need the following:

Permission to perform the operation on the artifact
Permission to access the environment containing the artifact

If you can’t access the environment containing the instance of the artifact you want or if you can’t perform an operation on the artifact, ask your mobile cloud administrator for permission.

Realm Lifecycle

Realms go through lifecycle stages similar to other artifacts. You begin by creating a realm and publishing it.

You learned about realms in Creating Realms. Now it’s time to discover how to take a realm through its lifecycle.

If you think you need a better understanding of how artifacts interrelate in the overall MCS lifecycle before exploring the lifecycle of realms, see Lifecycle.

Publishing a Realm

Realms are created and tested in a development environment. They can then be published and deployed to other environments.

Make sure you’re in the environment that contains the realm you want to publish.
Click and select Applications > Mobile User Management from the side menu.
Click the Realms navigation link.
Select the realm to publish.
Click Publish.
(Optional) You can enter a justification for publishing the realm in the Comment field.

After a realm is published, the user schema can’t be changed. Only data can be updated, including adding or editing mobile user information.

Creating a New Version of a Realm

You can create a new version of a realm, which can be in a Draft or Published state.

Make sure you’re in the environment containing the realm you want.
Click and select Applications > Mobile User Management from the side menu.
Click the Realms navigation link.
Select the realm.
In the right section, select More > New Version.
(Optional) Add a brief description that states what distinguishes this version from the previous one.
Click Create.

Deploying a Realm

You must have Oracle Cloud identity domain administrator permissions to deploy a realm. Only the user schema is migrated during deployment. No mobile app user data is migrated. In the target environment, the realm won’t have any users associated with it.

Sometimes deploying a realm along with its mobile backend and all the dependencies of that mobile backend can result in various permissions issues that can affect the deployment process. You can avoid these issues by deploying just the realm first and then deploying the mobile backends and its dependencies. This ensures that all the dependencies in the underlying security systems are resolved before deploying your mobile backend.

Make sure you’re in the environment containing the realm you want to deploy.
Click and select Applications > Mobile User Management from the side menu.
Click the Realms navigation link.
Select the realm to deploy.
In the right section, click Deploy.
The Source Environment field is read-only and automatically defaults to the current environment of the mobile backend.
Specify the target environment.
Only the environments for which you have permission to deploy to are listed. If the artifact you want to deploy has dependencies, you’ll have to resolve those dependencies before attempting to deploy.
(Optional) Enter a comment about the deployment.
Click Dependencies.
The Dependencies page lists the artifacts that the realm is dependent on. You can skip this page because realms don’t have dependencies on other artifacts.
Click Impact.
The Impact page lists artifacts in the target environment that will be affected when the realm is deployed. The data displayed is for your information only. Assess the effects and determine whether or not to proceed with the deployment.
Click Policies.
The Policies page is where you can view the policies in both the source and target environments and edit policy values as needed.
1. Click Export to see a diff file of the policies.properties file showing the policies in both the source and target environments.
2. (Optional) Edit a policy value as needed.
  To get descriptions of environment policies, see Oracle Mobile Cloud Service Environment Policies. If you need to know more about environment policies, see Environment Policies.
3. If you modified the policies.properties file, click Import to load it into the target environment.
  The User_DefaultUserRealm policy sets the realm version associated with a newly created mobile backend. In most cases, you’ll want to use the default value, which is 1.0.
  You might want to modify this policy if you create another realm, for example, if you create a second realm and you want new mobile backends to be automatically associated with it. Instead of setting it at deployment, you set this policy at the environment level (that is, go to the Administrator view, select the environment and set this policy by clicking Policies and editing the policies.properties file. The value is applied to all realms created in that environment, therefore, don’t set the value for a specific realm.)
Click Confirm and view the deployment configuration, then click Deploy.

To learn about deployment in MCS, see Deployment.

Moving a Realm to the Trash

Remove a realm by moving it to the trash.

Make sure you’re in the environment containing the realm you want to remove.
Click and select Applications > Mobile User Management from the side menu.
Click the Realms navigation link.
Select the realm you want to remove.
In the right section, select More > Move to Trash.
Click Trash in the confirmation dialog if there are no dependency issues.
If you think you or someone else might restore it later on, enter a brief comment about why you're putting this item in the trash.

To learn how dependencies can affect moving an artifact to the trash, see Dependencies That Affect a Move to the Trash. To restore a realm that’s in the trash, see Restoring a Realm.

Restoring a Realm

Make sure that you're in the environment containing the realm you want to restore.
Click and select Applications > Mobile User Management from the side menu.
Click the Realms navigation link.
Click Trash ().
In the list of items in the trash, click by the realm you want and select Restore from Trash from the trash menu.
You can see an example of the trash menu in Restoring an Artifact.
Click Restore in the confirmation dialog if there are no conflicts.

Restoring an artifact can cause conflicts if a duplicate artifact already exists. To restore an artifact when a duplicate artifact exists, see Restoring an Artifact.

Managing a Realm

When at least one realm exists, you’ll be taken to the Mobile User Management page every time you click and select Applications > Mobile User Management from the side menu. On the left side of the page, you see a list of all the mobile backends, their version numbers, and their Draft or Published state (mobile backends in Trash aren’t displayed).

On the upper right side of the Realms page, you can open, test, publish, and deploy your realm. You can view the user object properties defined for this realm also:

Description of realm_manage1.png follows

Description of the illustration realm_manage1.png

Click Trash to see which realms are in Trash.
Click Open to see details about the selected realm.
Click Publish to change the state of the realm from Draft to Published.
Click Deploy to deploy the realm to another environment.
Click More to create a new version, set the realm as the default realm, or move the realm to the trash.
Click User Object Properties to see information about the users assigned to the realm.

On the lower side of the page, you can examine deployment, usage, and history details:

Description of realm_manage2.png follows

Description of the illustration realm_manage2.png

Expand Deployments to see the environments that contain the selected the realm. You are only shown the environments that you have permission to access.

Click on an environment to switch to it.
Expand Used By to see the list of mobile backends that are associated with the realm.
Expand History to quickly see the latest activity for the realm.

Client Lifecycle

If your mobile app uses push notifications or you want to use analytics to examine and improve your app, you need a client. As a mobile developer, you associate a client, which represents a mobile backend binary, with a mobile backend. Clients go through similar lifecycle phases as other Mobile Cloud Service (MCS) artifacts with a few differences.

MCS can help you manage a client’s lifecycle. You can publish, deploy, and export a client. You can modify its version number and move it to the trash when you don’t need it anymore. Clients are top-level artifacts and their relationships with mobile backends can affect how clients and mobile backends are deployed, exported, imported, and moved to trash. see Client Management for details on creating clients.

If you want a general understanding of how artifacts interrelate in the overall MCS lifecycle, see Lifecycle.

Publishing a Client

When you’re satisfied with a client’s configuration, you can publish it but only if that client is associated with a mobile backend.

Make sure you're in the environment containing the client you want to publish.
Click and select Applications > Client Management from the side menu.
Select the client that you want to publish.
Click Publish.
Dependencies are checked and if the associated mobile backend is in Draft state, the confirmation dialog lists it and informs you that it will be published with the client. If the mobile backend is already published, no dependencies are shown.
If the mobile backend has downstream dependencies in Draft state, those dependencies will also be published. For example, MyClient 1.1 references MyMobileBackend 1.0. MyMobileBackend has dependencies on published MyAPI2.2 and unpublished MyAPI2.4. When you publish MyClient 1.1, the confirmation dialog only lists MyMobileBackend1.0 as a dependency but MyAPI2.4 is also published.
Click Publish All.
If the mobile backend is in the trash, you won't be able to publish the client. Cancel the publish operation, and either restore the mobile backend or associate the client with a different mobile backend. Then try publishing the client again.

Usually, once an artifact is published it can't be changed. In the case of clients, however, you can add or remove the notification profiles associated with the client even if that client is published.

Updating the Version Number of a Client

When you create a client, you assign it a version number that is usually the version of the mobile app that the client represents. You can update its version number at any time if the client is in a Draft state. This is useful if a change to the binary was made and you need a new version designation for the client.

If you need to modify the version number for a draft client, you just need to open that client and change the value in the Version field.

Make sure you're in the environment containing the client you want.
Click and select Applications > Client Management from the side menu.
Open the client that you want to update from the list.
On the Settings page, change the value in the Version field.
You'll get a message letting you know if you enter a duplicate version number (a version number that already exists for another client).

Creating a New Version of a Client

You can create a new version of a client regardless of whether it's in a Draft or Published state. When you create a new version of a client, you’re basically cloning the client configuration. You can then make changes to the new version. For example, although a client can be associated with only one instance of a backend, that backend can reference multiple clients. You could create new versions of a client, where each client corresponds to a specific platform of a mobile app (iOS, Android, and Windows), and then edit each client to reference the same backend.

Another reason for creating new versions is to create multiple clients for the same platform if there are multiple mobile app binaries for the same platform that use the same backend.

Note:

Unlike other artifacts, which require that the version number use the Major.minor format, the version number for a client should be the same as the mobile app binary that’s set by the app store. Depending on the version of the mobile app binary, the version could take the format of Major.minor or include an alphanumeric suffix with or without parentheses, a hyphen, space, or full stop. For example:

1.2
1.2 build 3452
1.2 (3452)
1.2–3452
1.2.3 (01–Jun-2016)

Click and select Applications > Client Management from the side menu.
Select the client that you want and then select More > New Version.
Enter a version number. (The same as the mobile app binary set by the app store.)
Click Save.

The new version is created in a Draft state.

Deploying Clients

When you have a published client that you’re satisfied with, you can deploy it to another MCS environment. The Deployment wizard takes you, the mobile cloud administrator, through the process of specifying your target environment, identifying any dependencies, and alerting you to any dependency issues. You'll have the opportunity to view any possible effects that deploying the client could have on other artifacts.

When you deploy a client, the associated mobile backend is automatically deployed with it.

Note:

When you deploy a client, its associated mobile backend is automatically deployed with it. However, if you’re deploying a mobile backend, the client associated with it isn’t deployed.

If you deploy a mobile backend without a client associated with it, you’ll have to create a client for it in the target environment.

After the client has been deployed, the copy of the client in the target environment is assigned a new client ID and application key. Also the mobile backend associated with it is given an anonymous access key if HTTP Basic Authentication is enabled or a consumer key if OAuth is enabled. In addition, there's a different base URL for each environment. You'll need to incorporate all of these details into the apps that use this client.

You can view details for the client on the Clients page. The values applicable to that environment are shown in the Keys section, which includes the client application key value. To see the authentication and key information for the mobile backend, go to the Mobile Backends page.

On the Clients page, select your published client and click Deploy to open the Deployment wizard. Go to the links at the top of the wizard to complete these deployment steps:

Specifying a Target Environment for the Client
dependencies
policies
Deploying the Client

To learn more about deployment in MCS, see Deployment.

Specifying a Target Environment for the Client

After a client is published, the Deploy action is enabled. This step shows you how to designate a target environment.

Make sure you're in the environment containing the client you want to deploy.
Click and select Applications > Client Management from the side menu.
Select the published client.
In the right section, click Deploy.
The Source Environment field is read-only and automatically defaults to the current environment of the client.
Select the target environment for your deployment.
Only the environments for which you have deployment permission are listed. If the artifact you want to deploy has dependencies, you'll have to resolve those dependencies before attempting to deploy.
(Optional) Enter a descriptive statement about the deployment.

Identifying Dependencies and Deployment Impact

The next two navigation links let you view all the dependencies related to the artifact and whether they're currently deployed in the target environment. You can also see what impact the deployment might have on other artifacts.

When you deploy a client, the mobile backend that it references is also deployed. You can’t deploy a client unless it’s associated with a mobile backend.

Click Dependencies.
Lists artifacts that must already be deployed to the target environment and on which the current artifact depends. You can see potential deployment issues, such as version conflicts, missing implementations (depending on the artifact), and so on. This gives you the opportunity to cancel the deployment and fix any potential issues. Afterward, you can go back and deploy your artifact.

Note:
You won’t see profiles listed because profiles aren’t deployed with clients. You’ll have to manually create the profiles you need in the target environment after you deploy the client.
Click Impact.
Shows notifications of possible effects on the artifact. The data displayed here is for your information only. Assess the effects and determine whether or not to proceed with deployment. If there's an issue, you can cancel the deployment process. After the issue is resolved, you can try deploying again.

Setting Environment Policies for Clients

Each environment has policies that govern the behavior of the artifacts within that environment. Policies and policy values in one environment can differ from policies in another environment. For instance, if you're deploying from a development environment to a runtime environment, you might want a higher degree of logging information in the runtime environment because your artifact will be thoroughly tested there prior to being made publicly accessible. The Policies page is where you can view the policies in both the source and target environments and edit policy values as needed.

Click Policies.
Click Export to see a diff file of the policies.properties file showing the policies in both the source and target environments.
To get a description of policies and their default values, see Oracle Mobile Cloud Service Environment Policies. See Environment Policies for a general discussion on environment policies.
If you modified the policies.properties file, click Import to load it into the target environment.

To see what policies need to be updated in the target environment, go to the deployment instructions for the specific artifacts.

Deploying the Client

View the basic details of your client deployment: the current environment, the target environment, and any dependencies or policies. You can cancel or go back if you want to make changes to your deployment. If you're satisfied, you can deploy the client.

Click Confirm.
The details of the deployment are displayed in a read-only section.
Click Deploy.
A confirmation page is displayed that informs you if the deployment succeeded.

After a successful deployment, you can return to the Clients page or go to the Administration tab to review the policy settings in the target environment.

You can manually add notification profiles to the client in the target environment.

Moving a Client to the Trash

Remove a draft or published client by moving it to the trash. If the client is needed later on, you can restore it from the trash.

Note:

Moving a client to the trash does not move the associated mobile backend or any profiles referenced by the client to the trash.

Make sure you're in the environment containing the client you want to remove.
Click and select Applications > Client Management from the side menu.
Select the client, then select More > Move to Trash.
Click Trash in the confirmation dialog if there are no dependency issues.
If you think you or someone else might restore it later on, enter a brief comment about why you're putting this item in the trash.

To find out how dependencies can affect moving an artifact to the trash, see Dependencies That Affect a Move to the Trash. To restore a client that's in the trash, see Restoring a Client.

Restoring a Client

Make sure that you're in the environment containing the client that you want to restore.
Click and select Applications > Client Management from the side menu.
Click Trash ().
In the list of items in the trash, click by the client you want and select Restore from Trash.
Click Restore in the confirmation dialog if there are no conflicts.

Restoring an artifact can cause conflicts if a duplicate exists. To find out more about restoring an artifact when a duplicate artifact exists, see Restoring an Artifact.

Managing a Client

When at least one client exists, you'll be taken to the Clients page every time you click and select Applications > Client Management from the side menu. On the left side of the page, you see a list of all the clients, their version numbers, and their Draft or Published state (clients in the trash aren't displayed).

On the Clients page, you can open, test, publish, deploy, see the client dependencies, history, and the environments containing the client:

Description of the illustration client_keys.png

Click Open to see details about the selected client.
Click Publish to change the state of the client.
Click Deploy to deploy the client to another environment in the same MCS instance.
Click More to create a new version, export the client to another instance of MCS, or move the client to the trash.
Click Trash ( ) to see which clients are in the trash.
Expand Keys to obtain the values for the client ID and the application key.

To see application key and client ID information for clients deployed to another environment, click on an environment in the Deployments section.
Expand Notifications to see which push notifications, if any, are enabled for this client.

On the lower right side of the page, you can view data about the selected client:

Description of client_manage.png follows

Description of the illustration client_manage.png

Expand Dependencies to see the mobile backend that this client references.

Note:
Only the mobile backend is listed. If the mobile backend has downstream dependencies, go to Applications > Mobile Backends and view them from the Dependencies section of the selected mobile backend.
Expand Deployments to see the environments that contain the client. Note: You're only shown the environments that you have permission to access.

Click on an environment to switch to it.
Expand History to quickly see the latest activity for the client.

Mobile Backend Lifecycle

You, the mobile developer, have created a mobile backend and now it's time to use it by publishing and deploying it. Remember that after you publish it, it becomes immutable, that is, you can't modify it.

If you want to make a change, you can create a new version of it. Because mobile backends are tightly integrated with custom code, APIs, and other objects in Oracle Mobile Cloud Service, you'll need to consider the relationships and dependencies on those objects.

If you think you need a better understanding of how artifacts interrelate in the overall MCS lifecycle before exploring the lifecycle of mobile backends, see Lifecycle.

Backend Lifecycle States

Relationships with other artifacts create dependencies. For example, your backend might depend on other artifacts, such as collections or APIs. When any artifact changes state, all dependent artifacts must also change states. Oracle Mobile Cloud Service keeps track of any dependencies for you.

Backends have the following activation states that determine whether they can be updated, deleted, or whether or not a new version can be created:

Active: Denotes the version of the backend is valid and active.
Quiesce: Denotes the version of the backend has become quiet, that is, it no longer supports new requests, and after all currently running requests are completed, it’s changed to Inactive. This is a transitional state.
Inactive: Denotes the version of the backend that’s present but not in an active state (that is, not usable).

If a user tries to access an API through an inactive backend, a 404 code is returned.
Deleted: Denotes the version of the backend that’s been moved to the trash and susceptible to a hard delete (actually removed from the repository).

Note:
Only mobile cloud administrators can purge (that is, permanently delete) an item in the trash.

Publishing a Mobile Backend

Follow these steps to publish a mobile backend. When a backend is published, all dependencies that aren’t yet published must also be published.

Make sure you’re in the environment containing the mobile backend you want to publish.
Click and select Applications > Mobile Backends from the side menu.
Select the mobile backend that you want to publish.
Click Publish.
The Confirm Publish dialog opens:

Description of the illustration mbe_publishsave.png
In the Confirm Publish dialog, click Check Dependencies to reveal whether or not the backend has dependencies and what those dependencies are so you'll know how to proceed:
- If you don't have dependencies, a confirmation dialog is displayed. Click Publish.
- If any dependencies are found in the trash, they’re listed. Cancel the publish operation, restore the dependent items from the trash, and restart the process.
- If there are dependencies in the Draft state, they’re listed in the confirmation dialog. You have the option to publish all the dependent artifacts along with your mobile backend. Click Publish All.

Published mobile backends can be deployed to your staging server or your production server.

Updating the Version Number of a Backend

If you created a new version of a backend using the New Version dialog, you can update its version number if it’s still in a Draft state. This is useful if you need to designate a different version number for it before you publish it or you’ve made a change to the configuration and you need a new version designation.

Make sure you’re in the environment containing the backend you want.
Click and select Applications > Mobile Backends from the side menu.
Select the backend you want to update from the list.
In the right section, select More > Update Version Number.
Enter a version number of the format Major.minor.

The previous version of the backend is displayed next to the field. You'll get a message letting you know if you've entered an existing version number.
(Optional) Add a brief description that states what distinguishes this version from the previous one.
Click Update.

A confirmation message is displayed. A draft of the new version is added to the list of backends.

Creating a New Version of a Backend

When you create a new backend, the version is automatically set to 1.0. As long as the backend is in a Draft state, you can change any aspect of it. As you develop your backend, you can change the version's major and minor version values as you see fit.

You can use a published backend as a root for a new version.

Make sure you’re in the environment containing the backend.
Click and select Applications > Mobile Backends from the side menu.
Select the published backend.
In the right section, select More > New Version.

The new version is created in a Draft state.

Note:

If the backend is associated with an API, you can’t associate another version of that API with the backend, regardless of whether the backend is in a Draft or Published state. You must create a new version of the backend and associate it with the other API version.

Deploying Mobile Backends

The Deployment wizard takes you, the mobile cloud administrator, through the process of specifying your target environment, identifying any dependencies, and alerting you to any dependency issues, such as associated APIs that aren’t deployed yet. You’ll have the opportunity to view any possible effect that deploying the mobile backend could have on other artifacts. Because you’re deploying from one environment to another, the policies applied to the mobile backend in the source environment may need to change in the target environment. You can view and modify these policies before you deploy your mobile backend.

After the mobile backend has been deployed, the copy of the mobile backend in the target environment is assigned a new mobile backend ID and either an anonymous access key if HTTP Basic Authentication is enabled or a consumer key if OAuth is enabled. In addition, there’s a different base URL for each environment. You’ll want to incorporate all of these details into the apps that use the mobile backend. You can view these details on the Mobile Backends page. Select the mobile backend and click one of the environments listed under the Deployments section. The values applicable to that environment are shown in the Keys section.

Select your published mobile backend and click Deploy to open the Deployment wizard. Go to the links at the top of the wizard to complete these deployment steps:

To learn about deployment in MCS, see Deployment.

Specifying a Target Environment for the Mobile Backend

After a mobile backend is published, the Deploy action is enabled. This step shows you how to designate a target environment.

Make sure you’re in the environment containing the mobile backend you want to deploy.
Click and select Applications > Mobile Backends from the side menu.
Select the published mobile backend.
In the right section, click Deploy.
The Source Environment field is read-only and automatically defaults to the current environment of the mobile backend.
Select the target environment for your deployment.

Only the environments for which you have deployment permission are listed.

If the artifact you want to deploy has dependencies, you’ll have to resolve those dependencies before attempting to deploy.
(Optional) Enter a descriptive statement about the deployment.

Identifying Dependencies and Deployment Effects

The next two navigation links let you view all the dependencies related to the artifact and whether they’re currently deployed in the target environment. You can also see what impact the deployment might have on other artifacts.

Click Dependencies.
Lists artifacts that must already be deployed to the target environment and on which the current artifact depends. You can see potential deployment issues, such as version conflicts, missing implementations (depending on the artifact), and so on. This gives you the opportunity to cancel the deployment and fix any potential issues. Afterward, you can go back and deploy your artifact.
If the call to the mobile backend that’s being deployed is rerouted, the name and version of the target mobile backend (as defined in the Routing_RouteToBackend policy for the mobile backend being deployed) is shown. The target mobile backend is not a dependency of the original mobile backend, so it won’t be automatically deployed. You must manually deploy the target mobile backend to the target environment if it doesn’t exist there already.
Click Impact.
Shows notifications of possible effects on the artifact. The data displayed here is for your information only. Assess the effects and determine whether or not to proceed with deployment.
If there’s an issue, you can cancel the deployment process. After the issue is resolved, you can try deploying again.

Setting Environment Policies for Mobile Backends

Each environment has policies that govern the behavior of the artifacts within that environment. Policies and policy values in one environment can differ from policies in another environment. For instance, if you’re deploying from a development environment to a runtime environment, you might want a higher degree of logging information in the runtime environment because your artifact will be thoroughly tested there prior to being made publicly accessible. The Policies page is where you can view the policies in both the source and target environments and edit policy values as needed.

Click Policies.
Click Export to see a diff file of the policies.properties file showing the policies in both the source and target environments.

Set the Sync_CollectionTimeoutToLive policy to specify the default amount of time you want data in a storage collection to remain in the cache.

If the call to the mobile backend being deployed is rerouted to another backend, set the Routing_RouteToBackend policy to specify the name and version of the mobile backend being deployed (the original mobile backend) and the target backend. The target backend is not automatically deployed with the original mobile backend. Deploy the target mobile backend to the target environment if it doesn’t exist there already. See Making Changes After a Backend is Published (Rerouting).

To get a description of policies and their default values, see Oracle Mobile Cloud Service Environment Policies.
If you modified the policies.properties file, click Import to load it into the target environment.

Deploying the Mobile Backend

View the basic details of your mobile backend deployment: the current environment, the target environment, and any dependencies or policies. You can cancel or go back if you want to make changes to your deployment. If you’re satisfied, you can deploy the mobile backend.

Click Confirm.
The details of the deployment are displayed in a read-only section.
Click Deploy.
A confirmation page is displayed that informs you if the deployment succeeded. For successful deployments, you can choose to return to the Mobile Backends page or go to the Administration tab to review the policy settings in the target environment.

Moving a Backend to the Trash

Remove a backend in a by moving it to the trash. A backend in the trash is no longer listed but it’s still viable, that is, it could continue to serve requests. If the backend is needed later on, you can restore it from the trash.

Note:

If a backend is referenced by a client, you can’t move that backend to the trash. If the backend is in Draft state, you can disassociate it from the client by opening the backend, selecting Clients in the navbar and clicking Delete (X) for that client. Then you can move the backend to the trash.

An alternative to removing a backend is to deactivate it, in which case it no longer services requests. See Deactivating a Mobile Backend for information.

Make sure you’re in the environment containing the backend you want to remove.
Click and select Applications > Mobile Backends from the side menu.
Select the backend.
In the right section, select More > Move to Trash.
Click Trash in the confirmation dialog if there are no dependency issues.

If you think you or someone else might restore it later on, enter a brief comment about why you're putting this item in the trash.

To find out how dependencies can affect moving an artifact to the trash, see Dependencies That Affect a Move to the Trash. To restore a backend that’s in the trash, see Restoring a Backend.

If you move a backend to the trash that has been redirected to another backend, the redirection still occurs.

Restoring a Backend

Make sure that you're in the environment containing the backend that you want to restore.
Click and select Applications > Mobile Backends from the side menu.
Click Trash ().
In the list of items in the trash, click by the backend you want and select Restore from Trash.
Click Restore in the confirmation dialog if there are no conflicts.

Restoring an artifact can cause conflicts if a duplicate exists. To find out more about restoring an artifact when a duplicate artifact exists, see Restoring an Artifact.

Deactivating a Backend

If you want to stop access to a backend without deleting it, you can do so by deactivating it. A deactivated backend can’t service any more requests. Deactivation is most common for backends in a Published state that have been replaced by newer versions and are no longer needed.

Make sure you’re in the environment containing the backend you want to deactivate.
Click and select Applications > Mobile Backends from the side menu.
Select your backend and click Manage.
In the dialog that appears, select Inactive from the drop-down list to deactivate the backend, or Active to reactivate an inactive backend.
Click Save.

If you deactivate a backend that has been redirected to another backend, the redirection still occurs.

Managing a Mobile Backend

When at least one mobile backend exists, you’ll be taken to the Mobile Backends page every time you click and select Applications > Mobile Backends from the side menu. On the left side of the page, you see a list of all the mobile backends, their version numbers, and their Draft or Published state (mobile backends in Trash aren’t displayed).

On the upper right side of the Mobile Backends page, you can open, test, publish, deploy, see runtime data about your mobile backend, and get authentication and application key values:

Description of the illustration mbe_keys.png

Click Trash to see which mobile backends are in the trash.
Click Open to see details about the selected mobile backend.
Click Publish to change the state of the mobile backend from Draft to Published.
Click Deploy to deploy the mobile backend to another environment.
Click More to create a new version, update an existing version, change the activation state, or move the mobile backend to the trash.
Look in the Metrics section to see the number of calls to the API associated with the mobile backend and the average response time.
Expand Keys to obtain the values for the mobile backend ID, anonymous key (click Show), and the application key for the associated client.

On the lower right side of the page, you view data about the selected mobile backend:

Description of the illustration mbe_manage.png

Expand Dependencies to see the artifacts the mobile backend is dependent on.
Expand Deployments to see the environments that contain the selected the mobile backend. You are only shown the environments that you have permission to access.

Click on an environment to switch to it.

Click Manage to change the activation state of the mobile backend.
Expand History to quickly see the latest activity for the selected mobile backend.

To see metrics information for mobile backends in another environment, for example Staging, switch to it by selecting Staging from the environment drop-down list (across from Metrics). Select Staging from the environment list across from Keys to see the HTTP Basic Authentication values in the Staging environment for the Mobile Backend ID, Anonymous Key, and Application Key fields.

To see metric and key information for mobile backends in the Production environment, choose Production from the environment drop-down lists.

Mobile Client SDK Demo Applications

The mobile client SDK provides a single demo application, FixItFast, which runs on each of the MCS-supported vendor platforms, iOS and Android.

FixItFast simulates an enterprise company application very close to what can be found in the real world. Its purpose is to give application developers a good idea of what’s possible and how this mobile application can be set up and run with MCS.

API Lifecycle

The lifecycle stages of custom APIs and API implementations are similar. Both artifacts go through a design-time phase where each is created, tested, edited, and then published.

The following figure shows the life stages of custom APIs and their implementations:

Description of api-lifecycle.png follows

Description of the illustration api-lifecycle.png

When you create a new custom API, its version is automatically set to 1.0 and it’s considered to be in a Draft state. In the Draft state, you can test and edit your API as often as needed.

When you’re satisfied with your API configuration, publish it with the understanding that a published API can’t be changed. APIs are implemented with custom code. To make a change to a published API, create a new version of the API. For custom APIs, you'll also need to create a new implementation for the new version.

As you develop your API, you can change the version's major and minor values as you see fit, that is, creating a new version of your API or updating an existing version. After you've implemented, tested, and published your API, you can deploy it to one or more environments (for example, you can deploy from a development environment to one or more runtime environments if you have multiple environments). Eventually, the API may become obsolete, and you can move it to the trash.

If you think you need a better understanding of how artifacts interrelate in the overall MCS lifecycle before exploring the lifecycle of custom APIs, see Lifecycle.

Publishing a Custom API

Before you can deploy a custom API, you must publish it first. As soon as it’s published, the API can’t be changed. You can create a new version of it, but you cannot edit it.

Note:

You must have an implementation associated with the API to publish it. A mock implementation is provided by default. To associate an implementation other than the mock implementation, open the API, and click Implementations in the left navigation bar. Select the implementation you want and click Set as Default.

Make sure you’re in the environment containing the custom API you want to publish.
Click and select Applications > APIs from the side menu.
Select the draft API that you want to publish.
Click Publish.

You can enter a justification for publishing in the Comment field.

When the API is published, you’re returned to the APIs page where you can see the updated status of your API.

Note:

Custom APIs can be published independently of implementations. When you publish an API, the implementation isn’t published automatically. To understand the relationship between custom APIs and their implementations, see Custom APIs and API Implementations.

Custom APIs and API Implementations

Oracle Mobile Cloud Service tracks a custom API as it's created, saved, published, deployed, implemented, deactivated, and reactivated. Custom APIs can be published independently or when a related mobile backend is published. The relationship between custom APIs and their implementations is given in the following sections.

Scope and Version Format

Both custom APIs and API implementations have versions that use the format Major.minor.

Active Versions

If you have multiple environments, each environment can contain multiple active versions of a custom API.

Though there can be multiple active versions of an API implementation per environment, only a single implementation version is mapped to a specific API version.

Draft and Published States

Both custom APIs and API implementation can have a Draft state or a Published state. A custom API can be published independently or published when a related mobile backend is published.

An API implementation can be published independently.

Actions Tracked by Oracle Mobile Cloud Service

MCS tracks the following operations for custom APIs: Create, Update, Publish, and Move to Trash.

MCS tracks the following operations for API implementations: Create and Save.

Number of APIs Referenced From a Mobile Backend

A mobile backend can reference multiple APIs, with each API having a specific version. That is, only one version of a given API can be referenced by a mobile backend. For example, a mobile backend can’t reference both myAPI1.1 and myAPI2.0, but it can reference both myAPI1.1 and yourAPI2.0.

An API implementation isn’t referenced directly by a mobile backend. The implementation is referenced by the API version, which is in turn referenced by the mobile backend.

Dependencies

A custom API is dependent on the active API implementation (as determined by the environment policy).

An API implementation is dependent on the API that implements it and other APIs that custom code call (as listed in the file manifest).

In reverse, mobile backends and API implementations are dependent on custom APIs. For an API implementation, it is a dependency of any APIs that list it as the active or default implementation.

Environment Policy Attributes

A custom API is affected by the API version to implementation policy mapping and the default API version setting.

An API implementation is affected by the number of node instances per virtual machine and standard runtime policies such as read-only, log-levels, etc.

At deployment, the API version to implementation policy mapping must be set in the target environment for a custom API. When deploying an API implementation, any policy that is referenced must be defined in the target environment.

For descriptions of environment policies and their values, see Oracle Mobile Cloud Service Environment Policies.

Updating the Version Number of an API

If you created a new version of an API using the New Version dialog, you can update the version number of the API if it’s still in a Draft state. This is particularly useful if you need to designate a different version number for it before you publish the API.

Make sure you’re in the environment containing the custom API you want.
Click and select Applications > APIs from the side menu.
Select the API you want.
Select More > Update Version Number.
Enter a version number of the format Major.minor.

The previous version of the API is displayed next to the field. You'll get a message letting you know if you enter an existing version number.
(Optional) Add a brief description that states what distinguishes this version from the previous one.
Click Update.

A confirmation message is displayed. A draft of the new version is added to the list of APIs.

Creating a New Version of an API

You can make a new version of a custom API regardless of whether it’s in a Draft or Published state. When you create a new version of a custom API, you are basically cloning the API configuration and making changes to it alone. You can specify the implementation to associate with the new version of the API. You can upgrade your custom API easily by creating a new version of it:

Make sure you’re in the environment containing the custom API you want.
Click and select Applications > APIs from the side menu.
Select the API.
You can create a new version of a custom API whether it’s in a Draft or Published state.
In the right section, select More > New Version.

Oracle Mobile Cloud Service checks for any dependencies on other APIs and for an associated implementation.
Enter a version number in the format Major.minor.

If you enter a version number that already exists, you'll get a message letting you know that number is already in use.
(Optional) Add a brief description that states what distinguishes this version from the previous one.
Click Create.

A confirmation message is displayed. A draft of the new version is created and is visible in the API Catalog.

Deploying APIs

To make a custom API accessible for use, it needs to be deployed to a runtime environment. Generally, a custom API would get deployed at the same time as the mobile backend with which it’s associated. When a new version of a custom API is published, it can be deployed to a target environment.

If you deploy an artifact that depends on an API not currently in the target environment, that API is automatically deployed, however, you won't be able to select the implementation for that API. If that API can’t be deployed (due to version conflict or not being in Published state, for example), the deployment process stops.

The Deployment wizard takes you, the mobile cloud administrator, through the process of specifying your target environment, identifying any dependencies and alerting you to any dependency issues, such as the implementation associated with the API is a mock implementation. You’ll have the opportunity to view any possible effects that deploying the API could have on other artifacts. Because you’re deploying from one environment to another, the policies applied to the API in the source environment may need to change in the target environment; you can view and modify these policies before you deploy your API.

Select your published custom API and click Deploy to open the Deployment wizard. Go to the links at the top of the wizard to complete these deployment steps:

To learn about deployment in MCS, see Deployment.

Specifying a Target Environment

After a custom API is published, the Deploy action is enabled.

Make sure you’re in the environment containing the custom API you want to deploy.
Click and select Applications > APIs from the side menu.
Select the published custom API.
Click Deploy.

The Deployment wizard opens on the Target page. The Source Environment is read-only and automatically defaults to the current environment of the API.
Select the target environment for your deployment.

Only the environments for which you have deployment permission are listed.

If the artifact you want to deploy has dependencies, you’ll have to resolve those dependencies before attempting to deploy.
Specify the implementation to associate with the API.

The default implementation is provided for you. If you don't want to use the default or if the default is a mock implementation, select another published implementation from the drop-down list.

You can deploy a custom API only if it’s associated with a published real implementation (that is, it’s not a mock implementation). The dependencies check in the next step shows the state of the associated implementation. If it isn’t published or if you don’t have a real implementation associated with the API, you’ll have to cancel the deployment and address the issue. Then you can try deploying the API again.
Enter a description about the deployment.

Identifying Dependencies and Deployment Effects

Click Dependencies.
Lists artifacts that must already be deployed to the target environment and on which the current artifact depends. You can see potential deployment issues, such as version conflicts, missing implementations (depending on the artifact), and so on. This gives you the opportunity to cancel the deployment and fix any potential issues. Afterward, you can go back and deploy your artifact.
If the call to the mobile backend that’s being deployed is rerouted, the name and version of the target mobile backend (as defined in the Routing_RouteToBackend policy for the mobile backend being deployed) is shown. The target mobile backend is not a dependency of the original mobile backend, so it won’t be automatically deployed. You must manually deploy the target mobile backend to the target environment if it doesn’t exist there already.
Click Impact.
Shows notifications of possible effects on the artifact. The data displayed here is for your information only. Assess the effects and determine whether or not to proceed with deployment.
If there’s an issue, you can cancel the deployment process. After the issue is resolved, you can try deploying again.

Setting Environment Policies for APIs

Each environment has policies that govern the behavior of the artifacts within that environment. Policies and policy values in one environment can differ from policies in another environment. For instance, if you’re deploying from a development environment to a runtime environment, you might want a higher degree of logging information in the runtime environment because your artifact will be thoroughly tested there prior to being made publicly accessible. The Policies page is where you can view the policies in both the source and target environments and edit policy values as needed.

Click Policies.
Click Export to see a diff file of the policies.properties file showing the policies in both the source and target environments.
(Optional) Edit a policy value as needed.
The policies that you’ll want to set at deployment are:
- Routing_BindAPIToImpl: Associates an implementation with the API.
- Network_HttpRequestTimeout: Sets the amount of time to read a request before the operation times out. The default value is 40,000 ms.
For a description of API policies and their default values, see Oracle Mobile Cloud Service Environment Policies. To learn about environment policies, including scope and naming formats, see Environment Policies.
If you modified the policies.properties file, click Import to load it into the target environment.

Deploying the API

View the basic details of your API deployment: the current environment, the target environment, and any dependencies or policies. You can cancel or go back if you want to make changes to your deployment. If you’re satisfied, you can deploy the API.

Click Confirm.
The details of the deployment are displayed in a read-only section.
Click Deploy.
A confirmation page is displayed that informs you if the deployment succeeded. For successful deployments, you can choose to return to the APIs page or go to the Administration tab to review the policy settings in the target environment.

Moving a Custom API to the Trash

Remove a custom API by moving it to the trash. If the API is needed later, you can restore it from the trash.

Make sure that you're in the environment containing the custom API that you want to remove.
Click and select Applications > APIs from the side menu.
Select the custom API you want to remove.
In the right section, select More > Move to Trash.
Click Trash in the confirmation dialog if there are no dependency issues.

If you think you or someone else might restore it later on, enter a brief comment about why you're putting this item in the trash.

Restoring a Custom API

Make sure that you're in the environment containing the custom API that you want to restore.
Click and select Applications > APIs from the side menu.
Click Trash ().
Make sure APIs is selected in the trash drawer.
In the list of items in the trash, click by the API you want and select Restore from Trash.
Click Restore in the confirmation dialog if there are no conflicts.

When you restore an API, its implementations are not restored with it. You’ll have to manually restore the implementations you want and designate an implementation as the default. Open the restored API, click Implementations from the navbar, and set an implementation as the default.

Restoring an artifact can cause conflicts if a duplicate artifact already exists. To restore an artifact when a duplicate artifact exists, see Restoring an Artifact.

Managing an API

After you create a custom API, you’ll want to edit it, publish it, see what implementations are associated with it, in short, you want to be able to manage the API and examine details of the APIs created by other service developers. The APIs page gives you access to all these features.

When at least one custom API exists, you’ll be taken to the APIs page every time you click and select Applications > APIs from the side menu. On the left side of the page, you’ll see a list of all the custom APIs except for those in the trash. You can see which APIs are in the Draft state and which are in the Published state. Every API is listed by its name and version number.

The right side of the page is where you can open, test, publish, and examine data about your custom API.

Description of api_manage_impls.png follows

Description of the illustration api_manage_impls.png

On the upper right side of the APIs page, you can perform the following actions:

Click Open to view details and settings for the selected custom API.
Click More to create a new version, update an existing version, or move an API to the trash.
Expand Implementations to see what implementations are available, along with their version numbers and whether they are in a Draft or Published state. Click Manage to go directly to the Implementations page.
Expand Deployments to see the environments that contain the selected the API. You are only shown the environments that you have permission to access.

Click on an environment to switch to it.

On the lower right side of the page, you view data about the selected API:

Description of api_manage_history.png follows

Description of the illustration api_manage_history.png

Expand Used By to see the list of the backends that call on the API.

Click All Usages to see the complete list.
Expand the History section to quickly see the latest activity for the selected custom API.

API Implementation Lifecycle

After you have an API implementation in a Draft state that’s configured and tested, you’re ready to publish and deploy it to another environment. API implementations go through the same lifecycle phases as APIs, in addition to being published and deployed, new versions can be created, existing versions can be updated, and obsolete implementations can be moved to the trash.

Remember that after an API implementation is published, it can’t be changed. If you’re still configuring and testing the implementation, keep it in a Draft state until it’s ready for the next phase of the lifecycle.

If you think you need a better understanding of how artifacts interrelate in the overall MCS lifecycle before exploring the lifecycle of API implementations, see Lifecycle.

Publishing an API Implementation

You can publish an implementation that contains real, non-mock data from the API Implementation page. Implementations can be published independently of APIs and can have separate versions as well. This lets you make changes to a published implementation, such as minor modifications or bug fixes, without requiring the API itself to be updated.

Make sure you’re in the environment containing the API implementation that you want to publish.
Click and select Applications > APIs from the side menu.
Select the API associated with the implementation that you want to publish.
Expand Implementations in the right section and click Manage.
The API Implementation page is displayed:

Description of the illustration api_impl_publish.png

You can see the list of dependencies by expanding the Dependencies section of the API Implementation page. The API associated with the implementation and any other APIs or connectors that the implementation calls are listed. You can see which dependency is in a Draft state, a Published state, or is unresolved.
Select the implementation and click Publish.
A dependency search is performed. If unresolved dependencies are found, the implementation can’t be published. Resolve the issue and try publishing the implementation again.

Description of the illustration api_impl_publish_confirm.png

If any API dependencies are declared through the Oracle-Mobile-API-Version header instead of through the package.json file, the API Designer isn’t aware of dependencies declared through the header and won’t prompt you with information when you publish the calling API. In this case, you must remember to publish the dependent API yourself.
If unpublished dependencies are found, click Publish All to publish all the listed unpublished artifacts.
If you don’t want to publish all the dependencies with your implementation, click X to cancel the operation. You can either publish the dependencies individually or edit your implementation to remove them.

When the implementation is published, the Deploy command is enabled.

Creating a New Version or Updating the Version of an API Implementation

Implementations can be published independently of APIs and can have separate versions as well. This lets you make changes to a published implementation, such as minor modifications or bug fixes, without requiring the API itself to be updated. You can create a new version of an API Implementation that is in a Draft or Published state. If you want to make changes to a published implementation, you must create a new version of it.

If you have previously uploaded an implementation with a given version specified and that implementation is still in a Draft state, you can replace that version without incrementing the version number. This might be desirable if you’ve uploaded the implementation and find, after testing the implementation, that there are further changes that you need to make before you can publish the changes. After you’ve published a version, that version is final.

You can also update the version number of an implementation in a Draft state. The process for both is the same. You set the version attribute in the implementation’s package.json file.

Open the package.json file and change the version attribute. For example, change “version”:”1.0” to “version”:”1.1”.
Upload a zip file of the modified implementation to the associated API version.

Some key points to know about implementation versions are:

Implementation versions are maintained independently of API versions. When you publish an API, the implementation isn’t published automatically.
When you upload a new version of an implementation, it becomes the default version (active implementation) for that API. You can change the default version in the API’s Implementations page.
The custom API’s Routing_BindApiToImpl policy defines the association between an API version and the implementation version.

Deploying an API Implementation

When an API implementation is published, it can be deployed to a target environment. Note that you must be a mobile cloud administrator to deploy an implementation. The Deployment wizard takes you through the process of specifying your target environment, identifying any dependencies and alerting you to any dependency issues, such as connectors that the implementation is associated with. You’ll have the opportunity to view any possible effect that deploying the API implementation could have on other artifacts. Because you’re deploying from one environment to another, the policies applied to the API implementation in the source environment may need to change in the target environment; you can view and modify these policies before you deploy your implementation.

Select your published custom API and click Deploy to open the Deployment wizard. Go to the links at the top of the wizard to complete these deployment steps:

To learn about deploying artifacts in MCS, see Deployment.

Specifying a Target Environment for the Implementation

Make sure you’re in the environment containing the API Implementation that you want to deploy.
Click and select Applications > APIs from the side menu.
Select the API associated with the implementation that you want to deploy.
Expand Implementations on the right and click Manage.
Select the implementation on the API Implementation page and click Deploy.
The Source Environment field is read-only and automatically defaults to the current environment of the API.
Select the target environment.
Only the environments for which you have deployment permission are listed.
If the artifact you want to deploy has dependencies, you’ll have to resolve those dependencies before attempting to deploy.
(Optional) Enter a description about the deployment.

Identifying Dependencies and Deployment Effects

Click Dependencies.
Lists artifacts that must already be deployed to the target environment and on which the current artifact depends. You can see potential deployment issues, such as version conflicts, missing implementations (depending on the artifact), and so on. This gives you the opportunity to cancel the deployment and fix any potential issues. Afterward, you can go back and deploy your artifact.
If the call to the mobile backend that’s being deployed is rerouted, the name and version of the target mobile backend (as defined in the Routing_RouteToBackend policy for the mobile backend being deployed) is shown. The target mobile backend is not a dependency of the original mobile backend, so it won’t be automatically deployed. You must manually deploy the target mobile backend to the target environment if it doesn’t exist there already.
Click Impact.
Shows notifications of possible effects on the artifact. The data displayed here is for your information only. Assess the effects and determine whether or not to proceed with deployment.
If there’s an issue, you can cancel the deployment process. After the issue is resolved, you can try deploying again.

Setting Environment Policies for an API Implementation

You’re almost ready to deploy the API implementation. Each environment has policies that govern the behavior of the implementation within that environment. Policies and policy values in one environment can differ from policies in another environment. For instance, if you’re deploying from a development environment to a runtime environment, you might want a higher degree of logging information in the runtime environment because your artifact will be thoroughly tested there prior to being made publicly accessible. The Policies page is where you can view the policies in both the source and target environments and edit policy values as needed.

Click Policies.
Click Export to see a diff file of the policies.properties file showing the policies in both the source and target environments.
(Optional) Edit a policy value as needed.
The policies that you’ll want to modify when you deploy an implementation are:
- CCC_Log_Body: Logs the request body when set to true ; useful for debugging purposes. The default value is false.
- CCC_Log_Body_MaxLength: Sets the character limit in the request body to log. The default value is 512. This policy is used with CCC_Log_Body.
In general, the default values for these policies should be sufficient.

For a description of environment policies and their default values, see Oracle Mobile Cloud Service Environment Policies. To learn about environment policies, including scope and naming formats, see Environment Policies.
If you modified the policies.properties file, click Import to load it into the target environment.

Deploying the Implementation

View the basic details of your API implementation deployment: the current environment, the target environment, and any dependencies or policies. You can cancel or go back if you want to make changes to your deployment. If you’re satisfied, you can deploy the implementation.

Click Confirm.
The details of the deployment are displayed in a read-only section.
Click Deploy.

You are taken back to the APIs page.

Moving an API Implementation to the Trash

Remove an API implementation by moving it to the trash. If the implementation is needed later, you can restore it from the trash.

Make sure that you're in the environment containing the API implementation that you want to remove.
Click and select Applications > APIs from the side menu.
Select the API associated with the implementation.
Click Implementations in the API navigation bar.
Select the draft API implementation to remove.
Click Move to Trash.
Only real implementations (not mock implementations) can be moved to the trash. If you’re moving the current default implementation to the trash, the next most recent version of the implementation is automatically set to the default. If no other implementations exist, the mock implementation is made the default.
Click Trash in the confirmation dialog if there are no dependency issues.

If you think you or someone else might restore it later on, enter a brief comment about why you're putting this item in the trash.

To find out how dependencies can affect moving an artifact to the trash, see Dependencies That Affect a Move to the Trash. To restore an API implementation that’s in the trash, see Restoring an API Implementation.

Restoring an API Implementation

Make sure that you're in the environment containing the API implementation that you want to restore.
Click and select Applications > APIs from the side menu.
Select the API associated with the implementation.
Click Trash ().
Select Implementations in the trash drawer.
In the list of items in the trash, click by the implementation you want and select Restore from Trash.
Click Restore in the confirmation dialog if there are no conflicts.

If you’re restoring an implementation that was used by an API, the implementation won’t be restored as the default (active) implementation for the API. You’ll have to reset the implementation as the default from the Implementations page (select the API and click Implementations in the navbar).

Restoring an artifact can cause conflicts if a duplicate artifact already exists. To restore an artifact when a duplicate artifact exists, see Restoring an Artifact.

Connector Lifecycle

The lifecycle stages of all connectors are the same. Each type of connector goes through a design-time phase where each is created, tested, edited, and then published.

For all connectors, there are the creation phase, the testing and editing phase, the publishing phase, and the deployment phase. When you create a new connector, its version is automatically set to 1.0 and it’s considered to be in a Draft state. In the Draft phase, you can test and edit your API as often as needed. When you’re satisfied with your connector configuration, publish it with the understanding that a published connector can’t be changed.

As you develop your connector, you can change the version's major and minor values as you see fit, that is, creating a new version of your API or updating an existing version. After you've implemented, tested, and published your connector, you can deploy it to one or more environments (for example, you can deploy from a design time environment to one or more runtime environments if you have multiple environments). Eventually, a connector may become obsolete, and you can move it to the trash.

If you think you need a better understanding of how artifacts interrelate in the overall MCS lifecycle before exploring the lifecycle of connectors, see Lifecycle.

Publishing a Connector

Before you can deploy a connector, you must publish it first:

Make sure you’re in the environment containing the connector you want to publish.
Click and select Applications > Connectors.
Select the draft connector that you want to publish.
Click Publish.
(Optional) You can enter a justification for publishing the connector in the Comment field.

When the connector API is published, you’re returned to the Connectors page where you can see the updated status of your connector.

Updating the Version Number of a Connector

If you created a new version of a connector using the New Version dialog, you can update the version number of the connector if it’s still in a Draft state. This is particularly useful if you want to create an alternate version of the current connector or need to designate a different version number before you publish the connector.

Make sure you’re in the environment containing the connector you want to update.
Click and select Applications > Connectors from the side menu.
Select the connector from the list.
In the right section, select More > Update Version Number.
Enter a version number of the format Major.minor.

The previous version of the connector is displayed next to the field. You'll get a message letting you know if you've entered an existing version number.
(Optional) Add a brief description that states what distinguishes this version from the previous one.
Click Update.
A confirmation message is displayed. A draft of the new version is added to the list of connectors.

Creating a New Version of a Connector

You can make a new version of a connector regardless of whether it’s in a Draft or Published state. When you create a new version of a connector, you’re basically cloning the connector configuration and making changes to it. You can make minor changes or expand upon already defined functionality to create a backward-compatible API. A major update, however, can result in a disruption of mobile services to your customers due to invalid values being requested or returned, an inability to read the same file formats as the previous version, and so on. Major changes, therefore, aren’t backward-compatible.

Make sure you’re in the environment containing the connector you want.
Click and select Applications > Connectors from the side menu.
Select a connector from the list.
You can create a new version of a connector whether it is in a Draft or Published state
In the right panel, select More > New Version.
Select whether the new version of the connector is backward-compatible with the previous version (the default selection).
Enter a version number in the format Major.minor.

If you enter a version number that already exists, you'll get a message letting you know that number is already in use.
(Optional) Add a brief description that states what distinguishes this version from the previous one.
Click Create.
A confirmation message is displayed. A draft of the new version is added to the Connector page.

Deploying Connectors

To make your connector accessible for use, it needs to be deployed to a runtime environment. When a new version of a connector is published, it can be deployed to a target environment. The Deployment wizard takes you, the mobile cloud administrator, through the process of specifying your target environment, identifying any dependencies, and alerting you to any dependency issues, such as an API implementation that calls on the connector. You’ll have the opportunity to view any possible effects that deploying the API could have on other artifacts. Because you’re deploying from one environment to another, the policies applied to the API in the source environment may need to change in the target environment; you can view and modify these policies before you deploy your connector.

Select your published connector and click Deploy to open the Deployment wizard. Go to the links at the top of the wizard to complete these deployment steps:

To learn about deploying artifacts in MCS, see Deployment.

Specifying a Target Environment

After a connector is published, the Deploy action is enabled.

Make sure you’re in the environment containing the connector you want to deploy.
Click and select Applications > Connectors from the side menu.
Click Deploy.
The Deployment wizard opens on the Target page. The Source Environment field is read-only and automatically defaults to the current environment of the API.
Specify the target environment for your deployment.

Only the environments for which you have deployment permission are listed.

If the artifact you want to deploy has dependencies, you’ll have to resolve those dependencies before attempting to deploy.
(Optional) Enter a description about the deployment.

Identifying Dependencies and Deployment Effects

Click Dependencies.
Lists artifacts that must already be deployed to the target environment and on which the current artifact depends. You can see potential deployment issues, such as version conflicts, missing implementations (depending on the artifact), and so on. This gives you the opportunity to cancel the deployment and fix any potential issues. Afterward, you can go back and deploy your artifact.
If the call to the mobile backend that’s being deployed is rerouted, the name and version of the target mobile backend (as defined in the Routing_RouteToBackend policy for the mobile backend being deployed) is shown. The target mobile backend is not a dependency of the original mobile backend, so it won’t be automatically deployed. You must manually deploy the target mobile backend to the target environment if it doesn’t exist there already.
Click Impact.
Shows notifications of possible effects on the artifact. The data displayed here is for your information only. Assess the effects and determine whether or not to proceed with deployment.
If there’s an issue, you can cancel the deployment process. After the issue is resolved, you can try deploying again.

Setting Environment Policies for Connectors

You’re almost done with the deployment. Each environment has policies that govern the behavior of the artifacts within that environment. Policies and policy values in one environment can differ from policies in another environment. For instance, if you’re deploying from a development environment to a runtime environment, you might want a higher degree of logging information in the runtime environment because your artifact will be thoroughly tested there prior to being made publicly accessible. The Policies page is where you can view the policies in both the source and target environments and edit policy values as needed.

Click Policies.
Click Export to see a diff file of the policies.properties file showing the policies in both the source and target environments.
Uncomment the policies for the connector.
The policies that you’ll want to uncomment when you deploy a connector are:
- Connector_Endpoint: Stores the endpoint URL of the connector.
- Network_HttpReadTimeout: Sets the amount of time spent waiting to read data.
- Network_HttpConnectTimeout: Sets the amount of time spent connecting to the remote service.
- Routing_BindApiToImpl: Specifies the implementation to which the connector API is bound.
- Security_OwsmPolicy : Specifies the security policy used for outbound security.
  
  Remember that when you deploy a connector, the credentials for any CSF keys defined for the connector’s security policies aren’t carried over to the target environment. You’ll want to tell your mobile cloud administrator to update the CSF keys so they can be used in the target environment.
The initial values for these policies are set when the connector is created.

Description of the illustration conn_deploy_policies.png

Note:
Be aware that the Connector_Endpoint and the Security_OwsmPolicy policies should never be set at the environment level, that is, the values for these policies shouldn’t be applied globally to all connectors within an environment. These policies should be set specifically to individual connectors.
For descriptions of environment policies and their default values, see Oracle Mobile Cloud Service Environment Policies.
If you modified the policies.properties file, click Import to load it in the target environment.

To learn about environment policies, including scope and naming formats, see Environment Policies.

Deploying the Connector

Click Confirm.
The details of the deployment are displayed in a read-only section.
Click Deploy.
A confirmation page is displayed that informs you if the deployment succeeded. For successful deployments, you can choose to return to the Connectors page or go to the Administration tab to review the policy settings in the target environment.

Moving a Connector to the Trash

Remove a connector by moving it to the trash. If the connector is needed later, you can restore it from the trash.

Make sure that you’re in the environment containing the connector you want to remove.
Click and select Applications > Connectors from the side menu.
Select the connector.
In the right section, select More > Move to Trash.
Click Trash in the confirmation dialog if there are no dependency issues.

If you think you or someone else might restore it later on, enter a brief comment about why you're putting this item in the trash.

To find out how dependencies can affect moving an artifact to the trash, see Dependencies That Affect a Move to the Trash.

To restore a connector that’s in the trash, see Restoring a Connector.

Restoring a Connector

Make sure that you're in the environment containing the connector that you want to restore.
Click and select Applications > Connectors from the side menu.
Click Trash ().
In the list of items in Trash, click by the connector you want and select Restore from Trash.
Click Restore in the confirmation dialog if there are no conflicts.

Restoring an artifact can cause conflicts if a duplicate artifact already exists. To restore an artifact when a duplicate artifact exists, see Restoring an Artifact.

Managing a Connector

After you create a connector, you’ll want to edit it, publish it, see what artifacts are associated with it, in short, you want to be able to manage the connector and examine details of the connectors created by other service developers. The Connectors page gives you access to all these features.

When at least one connector exists, you’ll be taken to the Connectors page every time you click and select Applications > Connectors from the side menu. On the left side of the page, you see a list of all the connectors except for those in the trash. You can see which connectors are in the Draft or Published state. Every connector is listed by its name and version number.

The right side of the Connectors page is where you can open, test, publish, or examine data about the connector:

Description of connector_manage.png follows

Description of the illustration connector_manage.png

On the right side of the page, you can perform the following actions:

Click Open to see details about the selected connector.
Click More to create a new version, update an existing version, or move an connector to the trash.
Expand Deployments to see the environments that contain the selected the connector. You are only shown the environments that you have permission to access.

Click on an environment to switch to it.
Expand Used By to see the list of the implementations that call on the connector.
Expand History to quickly see the latest activity for the connector.

Collection Lifecycle

The collection lifecycle involves moving from the Draft state to the Published state and finally deploying to the outside world.

Publishing is the prerequisite to deploying a collection. After you publish a collection, it can’t be modified. While you can publish a collection and also create a new version of a collection, you can also remove a collection as described in Moving a Collection to the Trash.

If you think you need a better understanding of how artifacts interrelate in the overall MCS lifecycle before exploring the lifecycle of collections, see Lifecycle.

Publishing a Collection

You create a collection within the context of a backend. When you’re satisfied with that collection, you can publish it.

Make sure you’re in the environment containing the collection that you want to deploy.
Click and select Applications > Storage from the side menu.
Select the collection you want to publish.
In the Details section on the right, click Publish.

Note:

You can publish a draft collection whenever you feel that it’s complete. After it's published, however, it can't be changed.

A collection can also be published involuntarily when a backend associated with a collection is published. If the associated collection isn’t yet published, it will be published automatically to support the backend.

When a collection is published:

Its metadata (its description and access roles) are frozen. To update the collections metadata, you must create a new version.
The major version (given the version that you arbitrarily defined) is incremented.
It’s no longer in your personal development space. It’s available for anyone with the proper permissions to associate with a backend.
Instance data isn’t moved with the collection.

Note:

Instance data (such as actual user objects or actual collection objects stored in collections) is typically created at runtime, or by user scripts or code as part of a configuration. It isn't moved with the collection.

The published collection can be deployed to different environments.

Updating the Version Number of a Collection

When you update a version, the new number is backward-compatible and the collection history continues.

Make sure you’re in the environment containing the collection that you want to update.
Click and select Applications > Storage from the side menu.
Select a collection.
In the Details section, select More > Update Version Number.
Specify an optional comment and click Update.

The collection history reflects the incremented number.

Creating a New Version of a Collection

You can’t copy a collection, but you can save yourself some time by creating a new version of an existing collection. If you create a new version, you’ll have the same data. It is possible to rename the collection and reset the version as long as the collection is in a Draft state.

If you want a collection that starts with 1.0 and that has the same data as another collection, you must make a new collection and import the data.

When you create a new version number, an independent collection is spawned from that point with a new history that’s unrelated to the previous collection. Any data is carried forward to the new version.

Note:

A collection can’t have more than one version of an object.

Make sure you’re in the environment containing the collection that you want.
Click and select Applications > Storage from the side menu.
Select a collection.
In the Details section on the right, select More > New Version.
Specify an optional comment and click Update.

Deploying a Collection

When a collection is published, it can be deployed to a target environment. The Deployment wizard takes you, the mobile cloud administrator, through the process of specifying your target environment, identifying any dependencies, and alerting you to any dependency issues, such as the realm the collection is associated with. You’ll have the opportunity to view any possible effect that deploying the collection could have on other artifacts. Because you’re deploying from one environment to another, the policies applied to the collection in the source environment may need to change in the target environment; you can view and modify these policies before you deploy your collection.

Make sure you’re in the environment containing the collection that you want to deploy.
Click and select Applications > Storage from the side menu.
Select the collection that you want to deploy.
In the right panel, click Deploy.

The Source Environment field is read-only and automatically defaults to the current environment of the collection.
Specify the target environment.

Only the environments for which you have deployment permission are listed.

If the artifact you want to deploy has dependencies, you’ll have to resolve those dependencies before attempting to deploy.
(Optional) Enter a comment about the deployment.
Skip Dependencies and move on to the Impact page.

The Dependencies page shows you the dependencies for the artifact being deployed. Because collections have no dependencies, you can skip this page.
Click Impact.

The Impact page lists artifacts in the target environment that are affected when the realm is deployed. The data displayed is for your information only. Assess the effects and determine whether or not to proceed with the deployment.
Click Policies.
1. Click Export to see a diff file of the policies.properties file showing the policies in both the source and target environments.
2. (Optional) Edit a policy as needed.
  The policies that you’ll want to set at deployment are:
  - Logging_Level: Sets the logging level.
  - Sync_CollectionTimeToLive: Sets the amount of time that data requested by a mobile application is stored in the cache.
  For a description of environment policies and their default values, see Oracle Mobile Cloud Service Environment Policies. To learn about environment policies, including scope and naming formats, see Environment Policies.
3. If you modified the policies.properties file, click Import to load it into the target environment.
Click Confirm and view the deployment configuration, then click Deploy.

Moving a Collection to the Trash

Remove a collection by moving it to the trash. Moving a collection to the trash means it’s no longer listed but it’s still viable. If the collection is needed later, you can restore it.

Make sure that you’re in the environment containing the collection you want to remove.
Click and select Applications > Storage from the side menu.
Select the collection you want to remove.
In the Details section on the right, select More > Move to Trash.
Click Trash in the confirmation dialog if there are no dependency issues.

If you think you or someone else might restore it later on, enter a brief comment about why you're putting this item in the trash.

Although only a mobile cloud administrator can purge a collection (eliminate it permanently), you can delete an object in a collection using the command-line operation, DELETE.

To find out how dependencies can affect moving an artifact to the trash, see Dependencies That Affect a Move to the Trash.

To restore a collection in the trash, see Restoring a Collection.

Restoring a Collection

Make sure that you're in the environment containing the collection that you want to restore.
Click and select Applications > Storage from the side menu.
Click Trash ().
In the list of items in the trash, click by the collection you want and select Restore from Trash.
Click Restore in the confirmation dialog if there are no conflicts.

Restoring an artifact can cause conflicts if a duplicate artifact already exists. To restore an artifact when a duplicate artifact exists, see Restoring an Artifact.

Managing a Collection

After you create a collection, you’ll want to edit it, publish it, and in short, manage the collection and examine details of collections created by other mobile developers. The Storage page gives you access to all these features.

When at least one collection exists, you’ll be taken to the Storage page every time you click and select Applications > Storage from the side menu. On the left side of the page, you’ll see a list of all the collections except for those in the trash. You can see which collections are in the Draft state and which are in the Published state. Every collection is listed by its name and version number.

The upper right side of the page is where you can open, test, and publish, deploy, and see which environments contain the selected collection:

Description of collection_manage1.png follows

Description of the illustration collection_manage1.png

Click Open to see details about the selected collection.
Click Publish to change the state of your collection from Draft to Published.
Click Deploy to deploy your published collection to another environment.
Click More to create a new version, update an existing version, associate the collection with a backend, or move a collection to the trash.
Expand Deployments to see the environments that contain the selected the collection. You are only shown the environments that you have permission to access.

Click on an environment to switch to it.

On the lower right of the page, you can examine usage and history details:

Description of collection_mange2.png follows

Description of the illustration collection_mange2.png

Expand Used By to see which backends are associated with the collection. To disassociate the selected collection from an artifact that uses it, click X next to the artifact’s name.
Expand the History section to quickly see the latest activity for the selected collection.