Essential Import Utility

A walkthrough of the Import Utility

Using the Essential Import Utility

The Essential Import Utility can be used to import bulk data from spreadsheets to quickly populate key classes and views. Some pre-configured spreadsheets and Import Specifications are available as part of Essential Launchpad and in our Essential View Loaders.
Essential Cloud and Essential Open Source both use the Essential Import Utility, but the mechanism is slightly different and so there is an instruction page for each.


Key Terms

Capture Spreadsheet – The spreadsheet that allows capture of bulk data
Import Spec - Specifies which classes and slots to send the data in the spreadsheet to
Reference Repository(Cloud Only) – defined in import settings, supplies the classes and slots available to the import utility
Target Repository (Open Source Only) – defined in import settings, supplies the classes and slots available to the import utility
Data Sources – Defines the source of data for an import, usually an excel spreadsheet
DUP – Data Update Pack – contains the data from the Capture Spreadsheet in a form that can be applied to Essential


JUMP TO

Import Utility for Essential Cloud
Import Utility for Essential Open Source


Import Utility for Essential Cloud

Setting Up the Import Utility

essential cloud import utility home

First you need to set up the Import Utility. From the homepage click on the Import Settings tab

essential cloud import utility settings

Step 1

Reference Repositories

To define a reference repository click New.
In the 'Create Reference Repository' window, add the name of the repository and click Upload to navigate to and upload a zipped version of the repository. Click OK.
NOTE: You only need to update the Reference Repository if new classes or slots are added to the meta model. If you add a new one, make sure the Reference? box is ticked. essential cloud import utility reference


essential cloud import utility repository setup


Step 2

Data Sources

To define a data source click New.
In the ‘Create Source Repository’ window, add the name of the data source, usually a spreadsheet. Click OK.
NOTE: You will need to add a new data source each time you want to create a new type of import.

essential cloud import utility source repository

Step 3

Go back to the homepage and select the Manage Imports tab.

essential cloud import utility activity


To set up a new Import Activity Click New and the ‘Create Import Activity’ window will appear.

essential cloud import utility activity create

  1. Name the activity
  2. Select Excel as your import type
  3. Choose the Data Source you set up in Step 2
  4. Click Upload and navigate to and select the spreadsheet to be imported, e.g. the Launchpad spreadsheet
  5. Ignore the other fields and click OK

Step 4

Select the Import Activity and click Open

essential cloud import utility activity open

Step 5

You will see the Import Activity Screen

essential cloud import utility activity home
  1. Use the Upload Import Specification button to upload the Import Spec for this activity. It will be an XML file; note it must be zipped.
  2. You can edit import specifications with the Edit Import Specification button. If you are using specification provided by the Essential team then there is no need to edit/amend these for the imports to work.
    Creating your own import specifications is not part of this how to guide.

  3. Source Spreadsheet
  4. This will contain the spreadsheet you uploaded in step 3.4. Note: You can upload later versions of the spreadsheet using the Upload Spreadsheet button

  1. Select Worksheets
  2. To ensure that you bring in only the data you want you can tick and untick worksheets and amend the start and end rows.
    Note: You don’t have to bring in all the worksheets in a spreadsheet, for example, you could bring in only the Applications worksheet from the Launchpad worksheet if that is all the data you have initially. The views populated will be dependent on the data you have imported. Equally, if you have added additional rows to the worksheet you can choose to just import these rows.
    Note: The import matches on ID and then Name, so if you want to add additional information, such as lifecycle, to applications you have already imported you can simply add the data and re-import as it will match to the existing applications in the repository. You can also use this to update data, for example, if you want to change an application name you can do so and then re-import – it will match on the ID and then update the name (although this would be easier to do in the repository itself!).

  3. Generate Data Update Pack
  4. Click the Generate DUP button. When it is complete you will see the screen to the right.
    Click the Download DUP File button and save the DUP somewhere.

essential cloud import utility DUP

Step 6

  1. Go back into the Essential Platform and ensure you are in the repository you want to apply the data to
  2. Now Select Import then select Data Import from the menu, you will see the Data Import screen
  3. Click the Browse button and select the DUP you generated and saved.
  4. The Summary line will show you which repository is selected
  5. Click the Apply Updates button to add the data to your repository
essential cloud import utility essential home
Note: we recommend taking a snapshot before any import and also suggest importing into the Sandbox repository first so you can check the data before importing into your pre-production or production repositories

Import Utility for Essential Open Source

Setting Up the Import Utility

First you need to set up the Import Utility. From the homepage click on the Import Settings tab

import utility setup
You will now see the screen shown to the right
import utility main

Step 1

Target Environments

You need to define a target repository, ie. a baseline to use, this is defined as a Target Environment. Click New Live to see the ‘Create Production Environment screen’.

  1. Create an environment name, usually the repository name
  2. Select a deployment type, either Local or Server depending on your install
  3. Use the Upload button to navigate to and upload a zipped version of the repository
  4. Note:The target repository should be your latest production repository, unless you are going to use the DUP option explained in Step 7.2. You will need to either update it here or in Step 6 or 7.

    OR, If you are server based enter your server details

  5. Enter the path to your viewer if you'd like to test or publish the repository directly
  6. This should be a test viewer as you should not test imports in the production viewer

import utility viewer
import utility settings

You will now be back on the Import Settings page, in the Target Environments section Click the New Dev/QA button to set up a test environment

  1. Create an environment name, usually the same as the production environment name but with Test or QA after
  2. Select a Deployment Role, either Dev or QA
  3. Selected the related Production Environment, this will be the one you created in the previous step
import utility environment

Step 2

Data Sources

To define a data source click New.
In the ‘Create Source Repository’ window, add the name of the data source, usually a spreadsheet. Click OK.
NOTE: You will need to add a new data source each time you want to create a new type of import.

import utility source

Step 3

Go back to the homepage and select the Manage Imports tab.

import utility home


To set up a new Import Activity Click New and the ‘Create Import Activity’ window will appear.

import utility start activity

  1. Name the activity
  2. Select Excel as your import type
  3. Choose the Data Source you set up in Step 2
  4. Click Upload and navigate to and select the spreadsheet to be imported, e.g. the Launchpad spreadsheet
  5. Ignore the other fields and click OK

Step 4

Select the Import Activity and click Open

import utility import

Step 5

You will see the Import Activity Screen

import utility activity
  1. Use the Upload Import Specification button to upload the Import Spec for this activity. It will be an XML file
  2. You can edit import specifications with the Edit Import Specification button. If you are using specification provided by the Essential team then there is no need to edit/amend these for the imports to work.
    Creating your own import specifications is not part of this how to guide.

  3. Source Spreadsheet
  4. This will contain the spreadsheet you uploaded in step 3.4. Note: You can upload later versions of the spreadsheet using the Upload Spreadsheet button

  1. Select Worksheets
  2. To ensure that you bring in only the data you want you can tick and untick worksheets and amend the start and end rows.
    Note: You don’t have to bring in all the worksheets in a spreadsheet, for example, you could bring in only the Applications worksheet from the Launchpad worksheet if that is all the data you have initially. The views populated will be dependent on the data you have imported. Equally, if you have added additional rows to the worksheet you can choose to just import these rows.
    Note: The import matches on ID and then Name, so if you want to add additional information, such as lifecycle, to applications you have already imported you can simply add the data and re-import as it will match to the existing applications in the repository. You can also use this to update data, for example, if you want to change an application name you can do so and then re-import – it will match on the ID and then update the name (although this would be easier to do in the repository itself!).

  3. Test Import
  4. Select the Test Environment from the dropdown, this will be the Dev/QA repository that you created earlier

  5. Click Test Import and you will see the ‘Test Import’ Screen

Step 6

  1. If you have changed the target repository click Refresh to update the target repository.
  2. Click Run Import – you will see the import working through the sheets. Depending on the amount of data this may take some time
  3. Click Download Messages and search for ‘warning’ and ‘exceptions’ to ensure there are no errors in the data
  4. If OK click Download to download a copy of the repository with the new data. You can then open the repository to check the data and publish, if required.
  5. You can optionally click Publish to Test Viewer to directly publish to the viewer you added in Step1.8 to test the data.
  6. You can optionally click Promote to Local Live to overwrite the target repository that you added in step 1.3.
  7. Note: You should test the result before doing this and you only use this if you want to replace the target repository.

  8. If you are using a local version of Essential Open Source once you are happy with the result you can promote this repository to your production environment.
import utility test

Step 7

If you are using a server based version of Essential Open Source you need to complete this step. If you are using a local version you do not have to complete this step if you have completed steps 5 and 6 in Step 6.
Once you have tested your import in Step 6 above and are happy with the result you can either Execute your import. You have two options:

  1. Click the Execute Import button. import utility execute
    You will see the ‘Live Import’ screen.
  • Upload the repository you want to add the data to
  • Click Run Import
  • - If you set up a server based repository in step 1 it will apply the changes directly to the repository
    - If you added a local repository it will apply the changes and update the target repository – much like clicking Promote to Local Live in the Test section
  • Click Publish to Viewer to publish to the viewer you added in Step 2

import utility live

Alternatively,

  1. Click the Generate Import File button. This will download a DUP to your downloads file, you should save the DUP somewhere sensible.
  2. import utility dup
  • Open your production repository and select the Essential Update tab
  • Click Choose and navigate to the DUP and select it
  • Check the Detailed progress box and click Apply Updates button to add the data to your repository
  • Save the repository with a new name, maybe as the next version.
  • Publish to the viewer



import utility upload