Apsona Items – managing your Apsona customizations

Overview #

Apsona for Salesforce maintains all its customization data in an object named Apsona Item. The records in this object are accessible to an administrator via the Settings – Apsona Items menu. This object includes records for

As an administrator, you can use the Apsona items screen to view and manage everything that Apsona creates in your org. You can use the usual filtering capabilities to find specific item records to examine and modify, as indicated in the screen shots below.

Common use cases #

Here are some common use cases where access to the Apsona Items is useful. Note that this menu is only available to Administrators.

Removing unneeded customizations. When in development mode, we often create lots of filters or reports which we then wish to remove. To do this, navigate to Settings – Apsona Items and find the items you wish to delete using the usual filtering tools, and then click Tools – Delete all.

Changing ownership of items. Suppose a user or consultant of yours has created a number of filters, reports or merge actions that you need, and you now need to take ownership of these items so that you can edit them. In this situation, you can simply find the Apsona Item records from this list (using the filter criteria) and use the Tools - Update all menu to update the ownership of these items to yourself or to any other user you choose.

Moving from sandbox to production. Suppose you have created a number of merge actions, reports or multi-step reports in a sandbox environment, and you now need to copy them over to a production org (assuming that both orgs have Apsona installed in them). You can accomplish this task in two steps:

  1. In your sandbox environment, export the needed Apsona Item records as described below.
  2. In your production org, navigate to Settings – Apsona Items, and then click Tools – Import items. Then provide as input the file produced from the above step. Apsona will then import all the items in your export file into the new org.

This export-import process assumes that the two orgs have identical API names for objects and fields. The Apsona Item records include references to these API names, so if you copy an Apsona Item record from one org to another, the item will fail to function correctly unless there is an exact match of the API names of the objects and fields it uses.

Exporting Apsona Item records #

You can export the contents of one or more Apsona Item records into a file, which you can then use as a backup or transport facility. To export one or more items:

  1. Navigate to Settings – Apsona Items, and filter the list so that you obtain only the items you need. If needed, use the check boxes to select just the items you need.
  2. Click Tools – Export items. 

    This will produce a file containing the internal representations of all of the Apsona Item records in your org. You can also perform a selective export by filtering down to just the items you want, and then exporting them.

The export file is not in CSV format, but rather an Apsona-specific JSON format. It contains not only the items you have selected, but also any items that might be implicitly required by the ones you have selected, traversing all dependencies as needed. In particular:

  • If you have included a merge action among the selected items, and if the merge action uses a document template (either Word or Excel), then the document template will also be included in the export file. Also included will be any reports or multi-step reports that the merge action needs in order to function correctly, e.g., as a data source for a record group.
  • If you have included a chart among the selected items, then any reports or multi-step reports needed by the chart will be included.
  • If a dashboard item is included in the selection, then all the items needed for that dashboard, either directly or indirectly – charts, reports or multi-step reports – will be included in the export file.
  • A given item is included only once in the export file, even if it is needed by more than one other item in the selection.

Importing Apsona Item records #

Before trying to import Apsona Item records, please ensure that your Apsona configuration includes access to the Document and Folder objects. (Please see the configuration page for information about setting up such access.) To import a set of Apsona Item records produced by an export, click Settings – Apsona items, then click Tools – Import items, and in the popup window that appears, select the file containing the records you wish to import. Apsona opens the selected file, parses its contents and displays a summary in the popup.

If the items include document templates for merge actions, the popup lets you specify the document folder into which the imported templates should be placed. If there are multi-step reports in the file, you can specify the folder into which the reports should be placed.

Clicking the import button will cause the items in the file to be imported into your Apsona Items object.

The import process automatically sets up the dependencies that existed among the exported items; for example, when importing a chart item, the import process will import any report items that the chart needs (since they will be included in the export file, as noted above) and set up the chart to refer to the correct imported item.

Please bear in mind that this import process does not check for duplicates – it simply creates new Apsona Item records for all data it finds in the export file.

Notes and caveats #

  • Be careful with editing the internals of the Apsona Item record. Specifically, do not edit any fields other than the name and description. Apsona’s algorithms rely heavily on the consistency of the internal data structures of the Apsona Item object, so it is possible to corrupt the item’s behavior if you edit its content.

Powered by BetterDocs