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.

Some Cloud customers may only have two environments, a Development/Staging system where both development and QA testing takes place, and a Production environment where the real-word operations occur.

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.

Managing Non-Importing Objects

Objects like Forms and Process Timelines are routinely imported into production from development or staging systems. Other objects, however, should not be considered routinely importable. Forms and Process Timelines usually have the same configuration on all systems, which makes them easy to import and export between systems. Some objects, however, might need to be configured quite differently on different installations.

As an example, let's take a look at a Datasource object. On a development or staging system, a datasource might be configured to connect to a test database that is populated with non-sensitive sample data. On a production system, however, the same datasource needs to be configured to connect to the database that stores production data.

On each server, therefore, you would have a Datasource with the same name, and which resides in the same location in the Content List, but each of the Datasource objects might be configured differently. Importing the same Datasource from a different server would overwrite the Datasource's proper configuration.

It's best to treat any object as non-importable if its configuration on a production system will differ from development or staging systems.

The first time you create a non-importing object on a development system, you might, for convenience, export it to staging or production initially. After the import, though, you would need to configure the object properly on each server onto which you import it. Once you have changed the configuration, any further changes to the object should be made manually on each server.

Global Objects

Non-importable objects also tend to be, though are not always, objects that are universally accessible. To return to the example of a Datasource object, each system should only have a single Datasource object that connects to a specific data store. Every Business Value or Custom task that needs to access that specific data store should access the same Datasource object. This datasource, therefore, is a global object that might be used across many applications. Moreover, by only having one global Datasource for each data store, any change you make to the Datasource is immediately reflected across all applications, making management much easier.

Another example might be a Goal. On a development system, a Goal may be configured to run evaluations on a very short time scale for testing purposes. On a production system, however, that Goal may only be evaluated once each day, week or month. Goals are global objects by design, because each Goal sets a universal system state when it is evaluated. So, you would usually not need to have two goals that make the same evaluation.

Similarly, some Business Rules might be global. Most of the time, a Business Rule makes an evaluation of some specific form or timeline data to return a value. This could be considered a "local" Business Rule, because it can't be used outside the context of the specific application in which it is used. On the other hand, a Business Rule might evaluate a Goal result, or a Business Value, and be used in many different applications, because the evaluation it makes is not specific to a Form or Process Timeline, allowing it to be run in any context.

Unlike non-importing objects, global objects may have the same configuration in production as they do on the staging or development servers. In those cases, importing them is not really an issue, but it might be wise to treat them in the same way you treat non-importing objects, in terms of how they are organized in the content list. Custom Tasks are an example of universal objects that you want to import when BP Logix updates the custom tasks. They are universal, but not non-importing, because you import them on a recurring basis, as updates are made available.

Organization for Non-Importing/Global Objects

Universal and non-importing objects should be organized into folders at the root level of the partition. These folders, and their contents, should be the same on each system. This rule means that if you have a Datasource named "ERP Data" located in a root folder named [Datasources] on your development server, it should also be placed in the same location on the production server. When you import any objects that use the datasource, Process Director will, during the import process, expect to find /[Datasources]/ERP Data in the Content List. If it does not, the system will generate an import error.

The most common example of this organizational method can be seen by looking at the [Custom Tasks] folder. The majority of Process Director applications use at least one Custom Task, either in a Form on in a Process Timeline. Because the Custom Tasks have the same name, and are found in the same folder location on every server, importing applications that reference Custom Tasks are generally trouble free.

To emulate this practice, you might want to consider following the organizational method that we use at BP Logix, and creating the following root folders, complete with the square brackets in the name:

[Custom Tasks]

[Data Sources]

[Goals]

[Business Rules]

[Business Values]

Using the square brackets as part of the name means that they will be organized together in the Content List, in both the tree view and folder view. Moreover, they can be shown or hidden in the content list by clicking the Show/Hide System Folders icon at the top of the Content List. Organizing objects this way in the Content List makes them easy to find, both for the import process, and for your implementers when they need to make configuration changes. And of course, they can be hidden from the Content List when convenient.