Importing/Exporting Content

When importing and exporting content, there are a number of vital considerations that need to be kept in mind. While import/export is a routine procedure, it must be done correctly to avoid serious problems. As such, it is important to discuss some best practices—not only in the import and export process itself, but in some basic practices for configuring Process Director objects.

In an ideal environment, there would be three different Process Director installations:

  • A Development system that is relatively open, and can be used for testing and development in a fairly unrestricted atmosphere.
  • A Staging system that exactly mirrors the configuration, users, permissions, and Content List structure of the production server. This server should replicate the production environment so that QA testing can be completed in a copy of the production environment before an implementation is moved to production. Fresh replications of the Production system should be made on the Staging server before any pre-release testing is performed.
  • A Production system where all of the real-world operations are conducted.

Content List Folders #

In Process Director, Content List Folders have two purposes.

First, they make it easier to establish permissions that allow different classes of users to access different Content List objects. The best practice is to set permissions only on folders, and not on individual Forms, Knowledge Views, Business Rules, etc. Permissions are inherited from parent objects, and when new child objects are created, they automatically have the same set of permissions as the folder in which they are contained. (If you change permissions on the folder, however, the permissions on objects within the folder won't be changed unless you click one of the “Replicate Current Permissions... buttons.)

Different folders might have different permissions to ensure that administrators, process managers, and users are only granted access to objects appropriate to their roles. For example, you might have certain Knowledge Views that only managers can access, while other Knowledge Views can be accessed by any user. In this case, you could create a Manager KViews and a User KViews folder. By setting the permissions of the Manager KViews folder to allow only Managers to view it, any Knowledge View that you place in the folder will inherit those permissions, and won't be accessible by other users.

It is important to remember, however, that permissions don't export. The first time you create a folder, manually or via the import process, you must explicitly set its permissions. Once you've done so, however, any new objects created or imported into the folder will automatically inherit the folder's permissions. (Remember to replicate permissions to child objects if the folder already contains objects.)

To use our example of the Manager KViews folder above, if you create new objects in the Manager KViews folder on Staging, then, when you reimport the folder to Production, all of the new objects will immediately be restricted to the permissions you set on the Manager KViews folder in the Production system. Because permissions don't export, you can set much less restrictive permissions on the Manager KViews folder in the Development environment to allow non-managers to test the system with non-sensitive data. When you re-import the folder to Staging and Production, the full set of access restrictions will be automatically applied to all the objects in the folder on the destination systems.

Folder Structure #

Structuring your folders properly makes it easier to deploy individual projects or implementations. As mentioned in the Creating Applications topic, the best practice for structuring folders is to organize them by application, and include subfolders for various Content List object types contained in the application. For instance, look at the sample structure below.

The image above is an example of structuring an implementation project logically. The top-level folder provides the name of the application you're modeling, in this case, a New Employee Onboarding process. All of the individual Forms, Knowledge Views, etc. are organized into the lower-level folders. With this type of organization, any changes you make to the application are contained inside this folder structure, which allows you to simply export the New Employee Onboarding folder, and import it into production, with all of its Content List objects intact, and without having to worry about interfering with any other application.

There are, of course, some exceptions to application-based organization. For instance, shared objects, like Datasources, Goals, and Business Values should probably each be grouped together in their own folder at the root level of the partition. You may have noticed that the Custom Tasks are organized in this fashion. You really shouldn't export/import Datasources between servers, to avoid mixing connections to test data with production data. The Data Sources should have exactly the same name, but the best practice is to create your Production and Staging Datasources manually. The important thing to remember is that you need to keep the folder structure exactly the same on your staging and production server, so that shared objects have the same relative paths on both servers.

Also, remember that any Datasources that are pointing to an external production system may need to be changed on the test server to point to an external test system. The same may be needed for some Custom Tasks that don't use a Datasource but connect to the external application directly, such as the Web Service CT. For the most part, this is important for external systems that are being updated from Process Director. If Process Director is just reading from the external system this may be less of an issue, but something you should keep in mind.

You may also want to create a root level Business Rules folder for those Business Rules that can be used in multiple projects. Business rules that are specific to a single project can be contained in the project's folder structure. Similarly, some common sub-processes might be organized into a root-level folder as well.

With the above in mind, a sample partition might look something like this:

Notice that the root folder contains folders for all of the shared objects, as well as the high-level organization for different types of applications the organization has implemented. At the second level, the HR Process folder contains the individual applications for various Human Resource operations. Finally, at the third level, the New Employee Onboarding folder contains folders for all of the Content List objects that are needed to run that specific application. BP Logix recommends that you implement a similar type of folder structure to make importing/exporting projects (not to mention simply finding things) easier.

Users and Groups #

Users and User Groups aren't imported or exported in Process Director when exporting applications (though they can, of course, be imported and exported separately by system administrators, using the procedure described below. So, be sure that any test users or groups to which a project refers in the Development environment also exist in Staging and Production. If you are syncing users in all three systems from Active Directory, this won't usually be a problem. But there may be cases where you've manually created users in the Development system, and in such cases, the users will have to be manually created on, or exported to, the Staging and Production systems prior to the application.

So, make sure that all users match in your test and production environments. If they do not, and you attempt to import a project with a reference to a user that doesn't exist on the target system, an import error will occur. (Keep in mind, though, that explicit references to individual users within an application's Process Timeline activities aren't a good idea to begin with.)

Speaking of import errors, if an import throws an error or warning...stop. Fix the problem and try again. There are several errors that are common when importing, such as the user mismatch we just discussed. Another very common error is forgetting to add a Datasource for a dropdown that uses the Fill Dropdown from DB Custom Task. Commonly, the problem arises when you create a new Datasource on the development server, but neglect to create a matching Datasource on the production system before performing the import. The bottom line is that if you see an import error, your project didn't import properly, so you need to fix the problem and try to import it again.

Another important caution to remember is to avoid manually renaming any Content List object on the target system (such as the Production system) that may ever be updated via import. Doing so can result in no end of problems the next time you perform an import. If you do need to rename an object, you must do that manually on both the destination and source servers prior to doing the import. The development/staging/production objects must all have the same names.

To understand why, we need to delve down a bit into how Process Director tracks objects, and how the import process works. Process Director is database-driven, meaning that every single object in Process Director is stored in a database. The database uniquely identifies every object by assigning it a special identifier known as a Globally Unique Identifier (GUID). A GUID is a 128 bit, 36 character value, and is a series of hexadecimal numbers that are created using algorithms that ensure uniqueness. The GUID is generally represented in the format:

aa213c6f-a8aa-454f-a04d-30b56fd2e493

GUIDs don't mean anything to us humans, of course, so we always provide logical names, like "Manager KViews", that we humans can understand when we create objects. But, in almost every case, Process Director never uses the name. It always uses the GUID. Two important exceptions to GUID-based identification are import/export, and when referencing objects and controls via the system variable syntax, e.g. {RULE:RuleName}, {:FieldName}.

But, GUIDs can't be exported or imported because they are unique. An object on the Staging system will have a completely different GUID than the parallel object on the Production system. Since that is so, the import process has to try and match the logical name that we have given the object when performing an import.

So, to return to our Manager KViews folder, if we change the name of the folder on the Production system to Mgr KViews, then the next time we import from Staging, problems will arise. The import process will be looking to match the Manager KViews folder on Staging with the same folder on Production. Because we've changed the name on production, however, the import can't match the text "Mgr KView" to "Manager KView". It will, therefore, ignore the renamed Mgr KViews folder on the Production system, and create a new Manager KViews folder on import. Similar problems arise if you rename the folder on the Staging system before importing it to Production.

The new Manager KViews folder won't have any of the restrictive permissions you placed on the original folder. As far as the Production system is concerned, the newly-imported Manager KViews folder is a completely new folder, with the default permissions that will allow anyone to access it. You now have a security hole in your Production system, while the secured object has been orphaned, with all of the imported links now pointing to an unsecured folder.

So, it is vitally important to remember that you should only rename objects in the target environment when there is a real need, and if you do, you must manually rename it in the source environment.

Now, at this point, you might be thinking that you could simply delete the orphaned object. But wait, it gets worse.

If there are other objects on the production system that were not part of the import, and that were linked to the Mgr KViews folder when you renamed it, those links still exist. Those object links were not replaced with links to the Manager KView folder. So, now, your production system may have some objects linked to the Mgr KViews folder, while other objects are linked to the unsecured Manager KViews folder.

If you simply try to delete an orphaned object, the remaining links to orphaned object will now be broken, so you may break all of those related applications as well. But, even worse, when you delete an object, you also delete every instance of that object. That might not be a big deal if the object is just a Knowledge View, but if the object is a Process Timeline or Form, then every single instance of that object, and all of the data associated with those instances, will be deleted from the system. You have just deleted all of the historical data in your system for that process or Form. Also, you'll delete any link that any other object has to the object, so may destroy more than one application.

If you find yourself in a situation like the above, where you've renamed an object, performed an import, and now have two objects, you have two options. First, you can call BP Logix Technical Support for assistance, which is your best option. Second, you can try to fix the problem yourself by following the procedure below:

  1. Back up your Process Director database for the Production system.
  2. Identify the new objects that were just created on the Production system because they were renamed.
  3. Remove the new objects from Production.
  4. Rename the objects on Production so they match the Staging system.
  5. Re-import the objects.

With the above in mind, you may conclude that, as long as you aren't importing or exporting, you can rename or delete objects that don't have instances, like KViews or Business Rules, without running into problems. But, that's not completely true either, because, in addition to importing/exporting, there is one other case where the name of the object, rather than the GUID, is vitally important. Sometimes, you refer to objects through System Variables.  For instance, you might have a condition in a process or Form that relies on the result of a Business Rule where you've used a System Variable to return the result, e.g., {RULE:RuleName}. System Variables are name-based, not based on the GUID. That means that if you rename or delete an object that is named in a System Variable, you'll break the object that uses the System variable as a reference.

The general rule, therefore, is that deleting object definition in the Content List of a Production system is an extraordinarily bad idea. If you do so, and eliminate vital historical data, then you have to try to restore your database which is a complicated and risky course of action.

So, to avoid the massive headaches any deletion can cause, only Partition Administrators should be able to delete anything on Production. Moreover, no actual user should ever be given Partition Administrator privileges, in order to ensure that no user can accidentally delete anything.

Instead, create a specific Partition Administrator account, and require administrative personnel to log out of their personal accounts and log into the Partition Administrator account before deleting anything. And even then, they should take extraordinary care before deleting an object. There are, in fact, a number of other security options you should consider as well, all of which can be found in the Securing Process Director section of the System Administrator's Guide.

Exporting and Importing Objects #

Other Functions #

Home Page Import Wizard #

For Process Director v6.0.300 and higher, a wizard located on the Home page can be used to import a PDZ file containing Content List objects.

Important This is a documentation stub for an upcoming Process Director feature, and is subject to change without notice.

Complex Application Imports #

When creating a new application, there may be other Process Director objects, like Workspaces and Meta Data categories, created as part of the application. Exporting other Process Director Objects, like Workspaces or Partition Meta Data, is done from the IT Admin area of the installation, on the appropriate page for administering those item types. For example, to export a workspace, you must go to the Workspace page of the Configuration section to perform the export.

The process for exporting these objects is very similar to the method for exporting Content List items. Each object type must be exported separately, and are exported into their own separate PDZ files.

These associated objects will need to be imported separately from the Application folder, and the order in which these other objects are imported is critical to avoid import errors. Process Director objects exist in a hierarchy, where lower-level objects can only import correctly if the associated higher-level objects already exist on the system. For instance, if a Form has a Meta Data Category assigned to the Form Definition, you can't import the Form correctly unless that Meta Data category already exists on the target system.

While the order in which you import objects to a target system is important, the order in which you export the objects from the source system is not.

To perform complex import operations like these, the Process Director objects should be imported in the following order.

  1. Partition Meta Data: Meta data can be applied to any Process Director object, which means it sits at the highest level of the Hierarchy.
  2. Users/Groups: Any new users or groups that have been created on the source system, and that are used in the application, must be imported. Exports of Groups and Users are, unlike other objects, exported and imported as Excel files rather than PDZ files.
  3. Partition-Level Content List Objects: If you have created additional Business Values, Dropdown Objects, or Business Rules that reside in the partition's "system" folders (e.g., [Business Values], [Business Rules], etc.), import them to the appropriate place in the Content List before importing the application. BP Logix does not recommend importing Datasource objects between systems. Instead, they should be manually created on the Production system, using the same name as they have on the Development/Staging systems. You should have a [Data Sources] folder at the partition root of all systems, which is where all Datasource objects should reside.

  4. Application Content List Objects: Once the higher-level objects have been imported, you can now import the PDZ file containing the application folder and all its contents.
  5. Workspaces: Workspaces are usually configured with specific groups or users assigned to them. Similarly, a Workspace may display an application Dashboard or Knowledge View, or have navigation buttons that reference application Forms. Importing Workspaces before importing the required objects will result in an import warning. The Workspace will be imported, but any missing users or groups or application objects will be removed from the Workspace.

Remember, failing to import objects in the proper order will result in import errors that will necessitate re-importing the objects.