26 Packages
Oracle Mobile Cloud Enterprise (OMCe) lets you share and move bundles of related artifacts built in OMCe to another instance of OMCe. You do this by exporting artifacts along with their dependencies, which creates a package, and importing that package to other instances of OMCe.
The export process creates a package file (package-
name.zip
) containing a copy of the artifact, its dependencies, and their local policies. You can also use the package file as an archive for a set of related artifacts and store it outside of OMCe. If artifacts in the current instance of OMCe are changed or accidentally deleted, you can retrieve their original state from the package.
If you’re a mobile or service developer, you can export artifacts such as mobile backends, collections, APIs and API implementations. You or another developer can then import the artifacts into the target environment.
What’s a Package?
A package is a container for one or more artifacts. If an artifact has dependencies, they’re also included in the package. For example, when you export a mobile backend, a package is created that contains the mobile backend and its dependencies, such as an API and its implementation, the connectors that the implementation calls, and collections. If the artifact you export is an API that has only one dependency, its implementation, then the package would contain just the API and its implementation.
Note:
While you can’t explicitly add roles to a package, if an artifact has roles associated with it, they’ll be included in the packageArtifacts can be in Draft or Published states. When an artifact is imported, it retains the state it had when the package was created (the source environment). That is, when an artifact in Draft state is imported, it’s still in the Draft state in the new instance. The same is true for artifacts in the Published state.
For information on exporting a package, see Adding Artifacts to the Package. For information on importing a package, see Uploading the Package.
Why Do I Want a Package?
With packages, you can easily share artifacts across different instances of OMCe. For example, you might find that you can use the same set of configured artifacts for different apps. Instead of having to recreate the same set of artifacts with the same configurations in another instance of OMCe, you can export the artifacts (that is, create a package) in the current instance and import them into the target instance of OMCe where work on the other app is being done.
Lets say Jeff, the service developer for Fix It Fast, has created a mobile backend that lets a technician look up the latest service requests and find the location and contact details for each customer. Fix It Fast has a subsidiary business called Restore It Fast, which provides restoration services to customers with fire or water damage. It would be helpful if the team at Restore It Fast could use that same mobile backend.
Jeff exports the mobile backend and all of its dependencies. He then notifies Jane, the service developer at Restore It Fast, that the package is ready to import. Jane locates and imports the package. She edits the environment policies for her OMCe environment. She saves significant time by having the essentials of the mobile backend completed. She can begin testing right away and have the app ready to use by Restore It Fast technicians.
Exporting a Package
Use the Export Package wizard to easily create a packaged set of artifacts that you can export to other instances of OMCe. The wizard shows you the dependencies associated with artifacts and includes those dependencies in the package for you. In addition to adding artifacts to the package, you’ll have the opportunity to modify local environment policies.
The Export Package wizard walks you through the following steps to export a package:
Reviewing Dependencies During Export
All artifacts are displayed under their respective types and top-level (root) artifacts are not distinguished. That is, a custom API that’s listed could be a dependency of a mobile backend or a top-level artifact itself.
Setting Environment Policies During Export
You can save some time by setting values now if you know what values will be required. For example, if a connector API is in the package, you may want to change the security policy. If a mobile backend is being exported, you may want to reset the Sync_CollectionTimeoutToLive
policy. Another example is if the call to the mobile backend that’s being exported is rerouted to another mobile backend and you want to ensure the rerouting occurs, you should set the Routing_RouteToBackend
policy here and specify the name and version of the original and target mobile backends. You’ll also want to check if the intended target mobile backend exists; otherwise, you’ll need to export it.
Note:
If a policy in the export package doesn’t already exist in the target, it will be added during the import.For descriptions of policies, see OMCe Policies and Values.
Completing the Export
Note:
When you click Export, artifacts are added to the package in their current state at that time. For example, if someone publishes an artifact while you’re creating the export package, the package will contain the published instance of that artifact.Re-exporting a Package
Importing a Package
Importing a package puts copies of the artifacts from the source environment into the target environment. Before you proceed with the import, make sure the package name and version are unique in the target environment. You won’t be able to import it if a package with the same name and version already exists. During the import, you’ll be able to verify the contents of the package, read the package documentation, and you’ll also be able to set the values for policies being added to the target environment or modify existing policies.
The Import Package wizard walks you through the following steps for importing a package:
Uploading the Package
Examining the Contents of the Import Package
Note:
The notification profiles associated with a client are not included in the import package. If you’re importing a client, you’ll have to re-create the notification profiles in the target environment and associate them with the client. See Notification Profiles and Client Apps.Setting Environment Policies During Import
Even if you don’t modify values for existing environment policies, any policies associated with the artifacts in the package that are new to the target environment are added for you when you update.
Check the documentation included in the package to see if any recommended values or policies are described. For descriptions of policies, see OMCe Policies and Values.
What Happens When You Import a Package?
Similar to deploying an artifact from one environment to another, when importing artifacts from one instance of OMCe to another, conflicts or errors can occur.
Some situations in which you can have a successful import:
-
If all the artifacts being imported to the target environment in the new instance of OMCe are unique in name and version from any existing artifacts in that environment, the import will be successful.
For example, a package contains the
MyIncidentReports 1.1
API. The target environment has aMyIncidentReports 1.5
API. There is no conflict because the two APIs are different andMyIncidentReports 1.1
is successfully imported. -
Another successful import occurs even if some of the artifacts in the package already exist in the target environment. That is, duplicate artifacts are in the target environment.
For example, a package contains
RightNow 1.1
connector. During the import process, it’s determined that a duplicate connector already exists in the target environment. It has the same name, version, and UUID values. The connector is skipped and the rest of the artifacts are successfully imported
Here are instances where potential problems can occur:
-
If a role associated with the artifacts in the package doesn’t exist in the target environment, then it is added when the package is imported, but to do so requires that you are a team member with Oracle Cloud identity domain administrator permissions. If you don’t have Oracle Cloud identity domain administrator permissions, the import will fail.
-
If some of the artifacts in the package are similar to existing artifacts in the target environment, that is they have the same name, version, but different UUID values, the import process can’t complete.
For example, the package contains the published
RightNow 2.0
connector and the target environment also has a publishedRightNow 2.0
connector. They both have the same name, version, but have different UUID values. You see aCONFLICT
message by the artifact and the import operation fails. When an import fails, all changes made to the target environment are rolled back. All artifact attributes and policy values are returned to their original values prior to the import.You have two choices. You can create a new version of the connector in the source environment, resolve any dependency issues, export the connector, and then import it to the target environment. Otherwise, you can move the
RightNow 2.0
connector that’s in the target environment to the trash and then proceed with the import.
For descriptions of the possible results of importing a package, see Import Results.
Import Results
The import results that can occur are described here:
Import State | Descriptions |
---|---|
Imported |
The artifact didn’t exist in the target environment and was imported successfully. |
Not Imported |
The artifact wasn’t imported because of conflict occurred or a missing artifact was detected. The import process was stopped and any changes made prior to the error were rolled back. The target environment is back to its original state before the import. |
Exists |
A duplicate artifact already exists in the target environment, therefore, the artifact in the package was skipped. |
Privileges |
A required role or realm didn’t exist in the target environment and the current user doesn’t have Oracle Cloud identity domain administrator permissions to create the role or realm automatically during import. |
Conflict |
A similar artifact (same name and version but different UUID) exists in the target environment. The import process was stopped and any changes made prior to the conflict were rolled back. The target environment is back to its original state before the import. |
Exporting Updated Artifacts
What happens if you make upgrades to artifacts in your instance of OMCe and you want those upgrades in another instance of OMCe? Lets say Jeff, at Fix it Fast, makes some changes to MyIncidentReports1.1
API, which is in Draft state. Samir, who works at Restore It Fast, would like to get the improved API.
When you import updated artifacts, you need to take steps to prevent a conflict. The actions you take depend on the Draft or Published state of the artifacts. That could mean you’ll have to move existing artifacts to the trash in the target environment or create a new version of the artifact to export and then resolve any resulting dependency issues with the new version of the artifact.
Following our example, Jeff exports MyIncidentReports1.1
API and its implementation. However, before Samir can import the package, he moves his Draft instance of MyIncidentReports1.1
to the trash to avoid a conflict during import.
Examining a Package
Moving a Package to the Trash
However, when you move an import package to the trash, what you’re actually doing is moving the package (that is, the record of the package) and all the artifacts in the package to the trash. Even artifacts in the Published state are moved to the trash. You can manually restore each artifact if you need them.
Environment Policy Settings for Packaged Artifacts
When you export artifacts, you save their configurations in a portable file (the package) that can be sent to various instances. Only local policies are included in the package. That is, only policies scoped for an artifact are available for editing and exporting. For example, if you’re exporting a mobile backend called FIF_Technician 1.0
and an environment policy has been defined for it that’s called FIF_Technician(1.0).*.Logging_Level
. That policy will be available for editing. Environment-wide policies are not included in the package file. For example, if the mobile backend uses *.*.Logging_Level
, that policy won’t appear on the Policies page. The mobile backend will be subject to the Logging_Level
policy in the target environment.
The environment policy settings for the artifacts are the values they have in the current instance. Because environment policies are specific to each environment in each instance, you might need to edit some of the policies before they can be used in their new location.
During export and import, you’ll have the option to edit these values for the target environment. If someone other than you is performing the import, you should document which policies might need to be modified, and which might be overwritten, and which might need to be added. You might also want to alert them to any roles or realms that are required. To ensure the required policies are added to the target environment.
If a policy that you set during export or import doesn’t exist in the target environment, it’s added when you import the package.
Any required roles or realms that don’t exist in the target environment are automatically created during the import but only if the person performing the import operation is a team member that has been granted an Oracle Cloud identity domain administrator role.
For descriptions of policies, see OMCe Policies and Values.