SmartCopy - Copy and Upgrade Project Versions
The SmartCopy module allows users to:
- export a version of a project from an account;
- import a previously exported version of a project into an account; and
- upgrade a previously copied version with a new exported version.
This module functions across accounts and across RunMyProcess instances.
1 Overview
SmartCopy facilitates the sharing of projects across accounts and the copying of a project within the same account. The copy will be completely independent of the original project.
The module enables users to:
- export a version of a project from an account;
- grant or remove authority for specific customers to import the project;
- delete an exported project;
- import a version of a project into an account (with authority).
The module can be used to distribute projects across different accounts but can also be used to create a copy of a project version within the same account.
2 Exporting a Project
Exporting a project will make it available for nominated customers to import into their accounts. Consideration should be given to the following points before proceeding with exporting a project:
- Resources for which there is no version control (i.e. resources that do not support the creation of revisions) will be exported in their current state. Please be aware that by importing an unversionable resource, any existing versions of the resource will be overwritten. Please see section 5 for further detail.
- Before exporting a project any hard-coded credentials should be removed.
- Collection names are unique only within an account. Before exporting a project it is worth considering naming conventions to limit the possibility of the same collection names being in use on other accounts.
- Pools and lanes used in project access rights will be exported; associated users will not.
- If the project uses resourceIDs in scripts or collections, these will remain in place. If the application relies on correct resourceIDs, it is recommended that they are obtained via platform APIs rather than hard-coded.
- Dictionaries set for the exported versions will be exported.
- By default, Data (e.g. the users belonging to a lane, standard files & collections) is not exported.
- If explicitely defined, standard files & collections data will be exported.
- A specific version of a project is exported therefore a version must exist before a project can be exported. A version can contain any amount of resources (e.g. a connector, a complete project, a partial project, sub-projects etc).
- We strongly recommend that you explicitly version all project resources, including all sub-projects. This will aid troubleshooting should a problem arise once the project has been imported - locating the correct revision on the original account will be straightforward. If all resources have not been explicitly versioned (i.e. the "keep updated" option has been used) and a problem arises, it is more difficult to identify the revision of the resource that has caused the problem as the current revision may be newer (due to the use of the "keep updated" option). If a project resource is NOT included (unchecked) in a version, the export procedure will try to export it but will check whether there are resource inter-dependencies.
To progress with exporting a project version, the user will need to enter their authentication details, only users with an ADMIN profile have the authority to export a project. Users will also need to identify the environment where the project is located at this point.
Once authenticated, the user will need to identify the project and the version that they wish to export and will be able to specify any data collections and files that should be included in the export. Files and data collections that are not included in the export will be exported without any data.
The user can then proceed to Export the project immediately or to Add Permissions before proceeding with the export. This option will allow you to specify who can import the project (see section 2.1).
The user will receive an email upon successful completion or failure of the export.
2.1 Granting Import Permissions
Granting permission for a customer to import an exported project can be done as an integral part of the export process or as a subsequent action for projects that have already been exported.
Before granting authority, the user has to be authenticated as an ADMIN user on the account that the project originated from and the target environment must be identified. If the permission is not being granted as part of the export process, the project and version also need to be identified.
Permission can be granted to all customers or to a specific customer, identified by their account id. After granting the permission, the project will be available for the customer to import into their account.
2.2 Revoking Import Permission
It is possible to revoke a previously granted permission. Before doing this, the user has to be authenticated as an ADMIN user on the account that the project was exported from and the target environment and the project must be identified.
After choosing the customer whose permission should be revoked and issuing the revoke, the customer will no longer have the ability to import the project.
2.3 Deleting an Exported Project
After exporting a project it is possible to cancel the operation, meaning that the project will no longer be available for import.
To do this, you will need to authenticate yourself as an ADMIN user on the originating account and identify the target environment, the project and the version.
After deletion the project version will not be available for import to any account.
3 Importing a new Project
In order to be able to import a project version into your account, the project owner must have exported the project version and granted your account permission to import it (see section 2.1). You will need to authenticate yourself as an ADMIN user for the account and to identify the target environment. There is no limit to the number of times an exported project can be imported to different domains / accounts.
You will be offered a choice of projects and versions that you have authority to import.
It is possible to import a project several times meaning that you can have one source project and several target ones on the same account. To facilitate this, whilst importing a project, you need to specify how you want the mapping between the source and the target project managed. The options are:
| Option | Description |
|---|---|
| None | The project will be imported as it is, with no relationship between the projects on the source and target accounts. Importing a specific project twice will result in two distinct copies of that project on the target account. |
| Unique | This is the default option and will create a unique, managed project on the target account, with a one-to-one relationship between the project on the source and target accounts. Importing the project more than once will update the same project on the target account. |
| Multi | This option will allow for the creation of multiple instances of the same project on the target account. A one-to-many relationship will exist between the project on the source and target accounts. This option does not support shared sub-projects. If you want to update a specific instance of the project on the target account you will need to specify the instance's project id. |
In order to easily identify the resources that have been imported, it is possible to specify a prefix and/or a suffix that will be added to the beginning or end of the names of resources that have been imported. The behaviour is specified below:
Prefix
The prefix specified will be added to the beginning of the name of the following resources for the imported project and its sub-projects:
- Project
- Organization
- Collections *
Suffix
The suffix specified will be added to the end of the name of the following resources for the imported project and its sub-projects:
- Project
- Organization
- Collections *
*You can further specify how to deal with the naming of collections by chosing to use the prefix and/or suffix for all collections or only for collections that already exist on the target account. The options are:
| Option | Description |
|---|---|
| Rename all | For each collection, create a new collection "COL" with the name [prefix]COL[suffix]{collectionId} |
| Rename if exists | For each collection that already exists on the acccount, create a new collection "COL" with the name [prefix]COL[suffix]{collectionId} |
Please note that as adding a prefix or a suffix changes the name of a collection, any code that references the collection by its name will need to be amended manually to reference the new name.
There are also options for dealing with the content of any Collections that already exist on the target accounts (i.e. have the same name):
| Option | Description |
|---|---|
| Overwrite | The content of any existing Collections will be overwritten with the content of the imported Collections. |
| Skip | The content of the existing Collections will remain as they are. |
| Error | If any Collection already exists, the import process will be aborted. |
Please note, it is possible for files and data collections to be excluded from an export, in this case they will have been exported without any data.
An imported project version will always be imported as a TEST version, regardless of whether the exported version was an ACCEPTANCE or LIVE version.
It is possible to further develop imported projects.
4 Upgrading Imported Projects
It is possible to import subsequent versions of a project that you have already imported.
The behaviour is determined by the use of the tracking flag:
| Option | Description |
|---|---|
| None | No tracking exists between the target and the source project. Subsequent imports of a specific project will result in further, distinct copies of that project on the target account. |
| Unique | This is the default option which creates an individually managed project for the target account. Importing the project subsequent times will update the project on the target account. The previous imported project version becomes a revision and the most recent imported project becomes the latest version. Any enhancements you have made will remain in the revision. |
| Multi | This option allows for the creation of multiple instances of the same project on the target account, each instance will have its own unique projectId. Subsequent imports of the source project will create further managed projects on the source account. If you want to update a specific instance of the project on the target account you will need to specify the instance's projectId. |
The repeated import of resources which are not versionable (see section 5) will result in the existing resource being overwritten by the latest import e.g. a standard CSS file (not versionable) used for a Web Interface will be overwritten by every import that contains that file. In the case of Collections, however, you will be given a choice of how to proceed during the import process:
| Option | Description |
|---|---|
| Overwrite | The content of the existing Collections will be overwritten with the content of the most recent imported Collections |
| Skip | The content of the existing Collections will remain as they are |
| Error | If any Collection already exists, the import process will be aborted |
5 Copied Resources Checklist
The table below provides a checklist of resources and whether or not they are versionable (i.e. support the creation of revisions). Please be aware that resources that are not versionable are overwritten when a new version is imported; for versionable resources a new version / revision is created.
| Resource | Support Mode | Versionable | Export Status |
|---|---|---|---|
| Web interfaces | Y | Y | The version included in the exported project version will be exported |
| Custom lists | Y | Y | The version included in the exported project version will be exported |
| Collections | Y | N | If explicitely specified, data will be exported in the exported project mode |
| Processes | Y | Y | The version included in the exported project version will be exported |
| Measures (Of a process) | N* | N | Will be exported in current state |
| Composite APIs | Y | Y | The version included in the exported project version will be exported |
| Organization | N | N | Will be exported in current state |
| Roles & Entities | N* | N | Will be exported in current state |
| Providers | Y | Y | The version included in the exported project version will be exported |
| Connectors | Y | Y | The version included in the exported project version will be exported |
| Reports | Y | Y | The version included in the exported project version will be exported |
| Standard files | N | N | If explicitely specified, will be exported in current state |
| Versioned files | Y | Y | The version included in the exported project version will be exported |
| Dictionaries | Y | Y | The version included in the exported project version will be exported |
* Measures, Scipted Lanes and Standard files are not versionable nor do they work across execution modes. An imported measure will therefore be effective in the production environment immediately.
6 Limitations
6.1 General
The following scenario taking place within one account will result in the creation of a new project:
- A project is exported;
- The project is imported;
- The exported project is deleted;
- The project is exported again;
- The project is imported again.
6.2 Export
- Circular references between projects through subprojects are not supported (P1 > P2 > P3 > P1);
- Only one export can be done at a time on any one account;
- If a project is updated during the export then the export could be corrupted.
- SmartCopy is not intended for mass data transfer (requiring more then 30min of processing time). If your source project contains collections that amount to 1GB or more, you should skip the collections during the export process and use the dedicated collection export/import instead.
- SmartCopy does NOT support connectors that are referencing a provider in a different project.
- SmartCopy does NOT support the use of "keep updated" when creating a version. Each resource should be specifically versioned.
6.3 Import
- A new revision is created for each resource that supports revisions (see section 5); resources that do not support revisions will be overwritten. Beware of importing an older version than what you currently have due to the risk of overwritting resources with older ones;
- Hard references to resources in code, collections or descriptions are NOT checked NOR adjusted during the import procedure. If you use hard references here, you will have to adjust them after importing on the target account.
- An import is for a specific version of a project only. It does not restore the revision history of a resource but only the revision specified in the version;
- An import can fail if resources are being edited and saved during the import phase.