Migrating Easy Form Data between Instances

1 Explanation of tables
2 Transforming User Keys

A space or page XML export does not contain Easy Form definitions for the forms or fields. It also does not contain the user submissions. That data is persisted in the database. The migration of Easy Form data requires the migration of the data in the database.

Easy Form data persistence is done using Active Objects (AOs): https://developer.atlassian.com/server/framework/atlassian-sdk/active-objects/

We are not aware of any Confluence tools/APIs that facilitate migration of AO data.

Active Object (AO) database tables are named with the prefix "AO" followed by a 6 character hash, "4025C4" and then the name of the object. The underscore ("_") character separates the parts of the name.

The names of the tables containing Easy Form AO data are:

AO_4025C4_CONFIGURATION_DAO
AO_4025C4_FORM
- CREATED_BY, UPDATED_BY contain user keys that may need to be transformed
AO_4025C4_FORM_FIELD
AO_4025C4_SUBMISSION
- USER_KEY contain user keys that may need to be transformed
AO_4025C4_SUBMISSSION_FIELD

Explanation of tables

AO_4025C4_CONFIGURATION_DAO
- App configuration data. You don't have to migrate this, you can just use the Easy Forms admin tool to setup configuration on your new instance
  - CREATED
    - timestamp
  - DESCRIPTOR
    - JSON descriptor like
      {"notifyWorkboxEditors":true,"notifyWorkboxUsers":false,"notifyWorkboxUsersList":"","notifyEmailIncludeData":false,"notifyEmailEditors":false,"notifyEmailUsers":false,"notifyEmailUsersList":"","notifyHipChatServer":"api.hipchat.com","notifyHipChatRoomToken":"","notifyWebhookUrl":""}
  - ID
    - PK id
  - UPDATED
    - timestamp
AO_4025C4_FORM
- Defines forms (not submitted form data)
- CREATED_BY, UPDATED_BY contain user keys that may need to be transformed
- PAGE_ID contains page IDs that may need to be transformed
  - CREATED
    - timestamp
  - CREATED_BY
    - user key
  - DESCRIPTOR
    - JSON descriptor like
      {"fields":[{"label":"Between 1 and 10 (inclusive)", "field_type":"number", "required":true, "field_options":...
    - FIELD_ORDER
      - ids of FORM_FIELD rows, comma separated, in order
    - HIP_CHAT_ROOM_TOKEN
    - ID
      - PK id
    - NAME
    - PAGE_ID
    - REPORTS _UNRESTRICTED
    - TITLE
    - UPDATED
      - timestamp
    - UPDATED_BY
      - user key
AO_4025C4_FORM_FIELD
- Defines fields in forms, FK to the form table (not submitted form data)
  - CID
    - client ID
  - CREATED
    - timestamp
  - DELETED
    - TRUE if deleted
  - FIELD_OPTIONS
    - JSON data like
      {"min":"1", "max":"10", "description":"", "integer_only":false}
  - FORM_ID
    - FK id of parent form
  - ID
    - PK id
  - LABEL
  - PLUGIN_VERSION
  - REQUIRED
  - TYPE
    - number, text, etc.
  - UID
  - UPDATED
    - timestamp
AO_4025C4_SUBMISSION
- User submissions for the forms
  - This table has a single row for each submission, used to identify/ID the submission values and associate them with a user
  - The individual values in the submission are in the submission field table (see below)
- USER_KEY contain user keys that may need to be transformed
- Data migration is only necessary if you want to preserve old submissions
  - ANONYMOUS_USER_KEY
    - hashed user ID, used for anonymous forms.
  - CREATED
    - timestamp
  - FORM_ID
    - FK id of parent form
  - ID
    - PK id
  - PLUGIN_VERSION
    - version of the Easy Forms plugin used for this submission
  - UPDATED
    - timestamp
  - USER_KEY
AO_4025C4_SUBMISSSION_FIELD
- User submission values for all of the fields on a form, one row for each field, FK to the submission table
  - CREATED
    - timestamp
  - FORM_ID
    - FK id of parent form
  - ID
    - PK id
  - NAME
    - input field name
  - SHORT_VALUE
    - the first 255 chars of the value, used for search filtering
  - SUBMISSION_ID
    - FK id of the parent submission
  - UID
    - input field UID
  - UPDATED
    - timestamp
  - VALUE
    - the CLOB value containing the entire value, used when the value is > 255 chars

Transforming User Keys

A username is unique on an instance. A username will be the same user on your source and destination but, depending on how you migrated your data from source to destination, your user keys that are mapped to those usernames may not be equal. The user keys might be different on your destination.

See the USER_MAPPING table:

The USER_MAPPING table maps a user key for each username. You will want to set the user keys in your Easy Form tables on your destination instance to match the user keys as used on the destination instance.