Available in: Axsy Mobile for Salesforce, Axsy Field Service, Axsy Public Sector, Axsy Retail Execution

Form Version Import provides a way to import the JSON for a Smart Form into a target Org, without the automatic creation of the corresponding Smart Form components - such as records representing Elements, Sections, Picklists, etc. - that are present in the source Org. The JSON for a Form Version is static and is essentially a snapshot of the definition of a Smart Form that the Axsy Mobile App is able to retrieve and display without requirement the corresponding Elements, Sections, Picklists, etc. being present in the target Org.

Please ensure you have exported the correct Form Version or Draft of your Smart Form by covering this article: Exporting Smart Forms

What Happens to the JSON When You Publish a Smart Form

When you publish a Smart Form, a versionId tag gets added to the JSON when it is created. This tag is what differentiates Drafts from Form Versions, as Draft Forms to not have the versionId tag when their JSON is exported. The presence or absence of this tag in the JSON being imported via Workbench also factors into how import of a Smart Form is handled (more details below).

Please see this article for more information on how to publish Smart Forms: Smart Forms - Versioning

Steps to Import a Form

Login to Workbench with the credentials for your target Org. Navigate to Utilities > REST Explorer and select the POST HTTP request option.

  1. In the POST request field insert /services/apexrest/axsy_forms/form?upsert or /services/apexrest/axsy_forms/form depending on the method you want to use (more details below).
  2. In the request body, paste the JSON from your exported Smart Form.
  3. Select Execute.

Form Version Import Methods

The presence of the versionId tag in the imported JSON will treat the import as a Form Version import. It should be noted that Form Version numbers are not imported across Orgs. For example, if you have imported three versions of a Form into the target Org but then create three more in the source Org, the sixth version in the source Org will become the fourth when imported into the target Org. 

Form Version Import with Upsert

  • Use POST request /services/apexrest/axsy_forms/form?upsert
  • No Smart Form components (such as records representing Elements, Picklists, Sections, etc.) are created in the target Org.
  • This method will import a published Form Version into the Org. However, this imported Form Version will not necessarily be accurately represented in the Designer, which will either be blank - if no Drafts of the Form are already present - or will display the latest Draft available in the Org, which will be superseded by the just imported Form Version.
  • Users will not be able to edit Form Versions in the target Org as there is no corresponding UI in the Designer and so they remain immutable. 

From Version Import without Upsert

  • Use POST request /services/apexrest/axsy_forms/form.
  • Importing a Form with this method into an Org where the Form doesn't already exist - either as a Draft or  as a published Form Version - will result in an error as there is nothing to update. The error will prompt the user to Upsert the Form. 
  • If a version of the Form does exist in the target Org, this method of Import behaves identically to Importing a Form Version with Upsert.  

Draft Form Import Methods

The absence of the versionId tag in the imported JSON will treat the import as a Draft Form import. While the methods of Draft Form import described below are still supported, they are considered deprecated.

Draft Form Import with Upsert

  • Use POST request /services/apexrest/axsy_forms/form?upsert.
  • If a Draft of the Form already exists in the target Org, this import method will look for the existing Draft and update changes that have been made to the Form in the source Org to the Form in the target Org. 
  • No new Form is created and nothing is removed from the target Org that has since been removed in the source Org. In other words, importing a Draft Form with Upsert will never delete a Form component or record. 
  • If no other Draft of the Form is already present in the target Org, a new Draft Form will be created.
  • Underlying Smart Form components are always created/updated and present in the Designer of the target Org – no duplicates will be created of existing components.
  • If you try and Upsert a Draft Form in a target Org where there are multiple Smart Form components that already share the same Name, an error will occur: "More than one record found..." This is because it is not clear which Smart Form component should be updated.

Draft Form Import without Upsert

  • Use POST request /services/apexrest/axsy_forms/form.
  • Importing a Draft Form without Upsert will always create a new Form. If a Draft of the Form already exists in the target Org, this import method will create a new Draft and duplicate any Smart Form components such as Elements, Sections, Picklists, etc. that are already present in the target Org. 

Make a Form Version a Draft for Import by Editing its JSON

You can make a Form Version a Draft by editing its exported JSON before an import. To do this, you need to remove the versionId tag in the JSON and save the file again. It will then be treated as a Draft Form during the import.

Manually Copy Description and Config Details

If you make use of the Description field and / or have a Smart Form Config that differs from the default, you will need to copy these over manually in the destination org. See screenshot below for reference.

Error Checking Using &nobatch

The import methods described in this article are performed asynchronously - which allows large JSON files to be imported via Salesforce Workbench. A disadvantage of asynchronous commands is that import validation error messages are not reported. If your JSON file size is smaller than approximately 500KB you can use the additional import parameter: &nobatch on any of the POST requests listed in this article to perform imports synchronously - which will allow any import validation errors detected by Salesforce Workbench to be reported. An example complete command is shown below: