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
- USER_KEY contain user keys that may need to be transformed
- Data migration is only necessary if you want to preserve old submissions
AO_4025C4_SUBMISSSION_FIELD
- User submissions for fields on the forms, FK to the submission table

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.