Last updated May 26, 2023

Rate this page:

Import Third Party data into Assets

This tutorial describes how to create a Forge app that imports third-party data into Assets. This app allows integrations with third parties by pulling data from external sources during an import. It also contains the triggers that are activated on the deletion, starting, and stopping of an import.

The final app looks like the following:

Assets Import Type Selection Screen.

Before you begin

This tutorial assumes you're already familiar with developing on Forge. If this is your first time using Forge, see Getting started for step-by-step instructions on setting up Forge.

To complete this tutorial, you need the following:

  • The latest version of Forge CLI. To update your CLI version, run npm install -g @forge/cli@latest on the command line.
  • The latest version of the UI kit. To update your version, navigate to the app's top-level directory, and run npm install @forge/ui@latest --save on the command line.
  • An Atlassian cloud site with Jira & Jira Service Management with Assets where you can install your app. You need to be an admin on the site to install the app.

This functionality of Assets is only available for Jira Service Management Cloud, PREMIUM and ENTERPRISE plans.

Create your app

The app allows integrations with third parties to allow data from external sources be imported into Assets via a Forge app.

  1. Navigate to the directory where you want to create the app.
  2. Create your app by running:
    1
    2
    forge create
    
  3. Enter a name for the app. For example, assets-import-app.
  4. Select the jira-service-management-assets-import-type-ui-kit template from the list.
  5. Open the app directory to see the app files.

Update the manifest

To register the functionality of your app, add jiraServiceManagement:assetsImportType and function modules to the manifest. The jiraServiceManagement:assetsImportType module adds entries to the create import menu, with the value of title and icon of icon. The function module contains logic that triggers off the certain actions.

  1. In the app's top-level directory, open the manifest.yml file.

  2. Replace the key, description, title & icon entry under jiraServiceManagement:assetsImportType with your values.

    1
    2
    jiraServiceManagement:assetsImportType:
      - key: '<your-module-key>'
        description: '<your-app-description>'
        title: '<your-import-type-name>'
        icon: '<your-icon-url>'
    

Your manifest.yml should look like the following, with your value for the app ID:

1
2
modules:
  jiraServiceManagement:assetsImportType:
    - key: hello-world-import-type
      function: renderImportConfig
      description: This is an Hello World! Forge App
      title: Hello World!
      icon: https://developer.atlassian.com/platform/forge/images/icons/issue-panel-icon.svg
      onDeleteImport:
        function: onDeleteImport
      startImport:
        function: startImport
      stopImport:
        function: stopImport
      importStatus:
        function: importStatus
  function:
    - key: renderImportConfig
      handler: index.renderImportConfig
    - key: onDeleteImport
      handler: index.onDeleteImport
    - key: startImport
      handler: index.startImport
    - key: stopImport
      handler: index.stopImport
    - key: importStatus
      handler: index.importStatus
permissions:
  scopes:
    - import:import-configuration:cmdb
app:
  id: '<your-app-id>'

Build, deploy, and install

Build, deploy, and install the app to see it in your Jira Service Management site.

  1. Navigate to the app's top-level directory and deploy your app by running:

    1
    2
    forge deploy
    
  2. Install your app by running:

    1
    2
    forge install
    
  3. Select your Atlassian product using the arrow keys and press the enter key.

  4. Enter the URL for your development site. For example, example.atlassian.net. View a list of your active sites at Atlassian administration.

Once the successful installation message appears, your app is installed and ready to use on the specified site. You can always delete your app from the site by running the forge uninstall command.

Running the forge install command only installs your app onto the selected product. To install onto multiple products, repeat these steps again, selecting another product each time. Note that the Atlassian Marketplace does not support cross-product apps yet.

You must run forge deploy before running forge install in any of the Forge environments.

View the app

With the app installed, it's time to see the entry in the create import menu.

Navigate to your Jira Service Management site, then click on Assets on the top tab.

  1. If you don't have an existing Object Schema, create one.
  2. In the Object schema you want to import into, select Schema configuration at top left.
  3. Select the Import tab.
  4. Click on the Create Import button to open the create import menu

You'll see the Hello World! entry from the app with the Atlassian Logo.

Implement the front end

Add the UI kit components that render when a user configures the import.

  1. Start tunneling to view your local changes by running:

    1
    2
    forge tunnel
    
  2. Open the src/index.jsx file.

  3. Modify to the contents of the file with this or place components you desire inside AssetsAppImportTypeConfiguration:

    1
    2
    // Import required components from the UI kit
    import ForgeUI, { render, Text, AssetsAppImportTypeConfiguration, useProductContext } from "@forge/ui";
    const App = () => {
      const { extensionContext } = useProductContext();
      const importId = extensionContext.importId;
      const workspaceId = extensionContext.workspaceId;
      const onSubmit = async () => {
         console.log("submit button clicked");
      };  
    
      return (
        <AssetsAppImportTypeConfiguration onSubmit={onSubmit}>
          <Text>Hello World!, ImportId = {importId}, WorkspaceId = {workspaceId}</Text>
        </AssetsAppImportTypeConfiguration>
      );
    };
    export const renderImportConfig = render(<App />);
    
  4. Refresh a Jira Service Management page on your site, navigate to Assets, edit your import associated with your app, and select Configure app.

    A modal dialog displays with:

    1
    2
    Hello World!, ImportId = {your-import-id}, WorkspaceId = {your-workspace-id}
    

In the code from this step:

  • The import statement lists the components to use from the UI kit. See UI kit components to learn more about these components.
  • extensionContext contains importId and workspaceId
  • AssetsAppImportTypeConfiguration is the component being rendered, make sure you place all your components inside it
  • Exporting the run constant provides the mechanism that renders the app.
  • onSubmit will be run when the Save configuration button is clicked.

Extension Points

These are pieces of code you can implement where Assets will call during the import process.

  1. onDeleteImport - Triggers off a deletion of an import structure

    1
    2
    const onDeleteImport = async (context) => {
       console.log("import with id ", context.importId + " got deleted");
    
       return {
          result: "on delete import",
       };
    };
    

    Deleting an Assets App Type Import Structure.

  2. startImport - Triggers off the start of an import

    1
    2
    const startImport = async (context) => {
        console.log("import with id ", context.importId + " got started");
    
        return {
            result: "start import",
        };
    };
    

    Starting an Assets App Type Import.

  3. stopImport - Triggers off the cancellation of an import

    1
    2
    const stopImport = async (context) => {
       console.log("import with id ", context.importId + " got stopped");
    
       return {
           result: "stop import",
       };
    };
    

    Stopping an Assets App Type Import.

  4. importStatus - Triggers to display the status of the import on the Imports UI

    1
    2
    const importStatus = async (context) => {
        console.log("import with id ", context.importId + " sending import status");
    
        return {
            status: "NOT_CONFIGURED"
        };
    };
    

    Showing progress on an Assets App Type Import.

    Showing progress on an Assets App Type Import.

There are two status enums that can be returned.

status: "NOT_CONFIGURED" will return the NOT CONFIGURED status as the first image shown above.

status: "READY" will return with the Import data button active as the second image shown above.

Import data into Assets via Imports REST API

The imports will be powered by the Imports REST API through its infrastructure. However instead of calling GET https://api.atlassian.com/jsm/assets/v1/imports/info to fetch the initial links to start the import process you will have to manually generate them. The three links mentioned in the Imports REST API in Step 3 can be found here where:

1
2
{
  "links": {
    "getStatus": "https://api.atlassian.com/jsm/assets/workspace/{workspaceId}/v1/importsource/{importId}/configstatus",
    "start": "https://api.atlassian.com/jsm/assets/workspace/{workspaceId}/v1/importsource/{importId}/executions",
    "mapping": "https://api.atlassian.com/jsm/assets/workspace/{workspaceId}/v1/importsource/{importId}/mapping"
  }
}

With Forge, you do not need to use a container token to call these endpoints, you can use asUser() or asApp() requests.

  • asUser() will perform the request on behalf of the user
  • asApp() will perform the request with the permissions of the app

More information about this responsibility model can be found here. Some examples of using asUser() and asApp() are provided below.

1
2
  const asUserRequest = await api
        .asUser()
        .requestJira(
                route`/jsm/assets/workspace/${context.workspaceId}/v1/importsource/${context.importId}/executions`,
                {
                   method: "POST",
                }
        );

Currently we only support asUser() requests to Imports REST API, we plan to support asApp() requests in the near future.

1
2
  const asAppRequest = await api
        .asApp()
        .requestJira(
                route`/jsm/assets/workspace/${context.workspaceId}/v1/importsource/${context.importId}/executions`,
                {
                   method: "POST",
                }
        );

The Import data button in the Imports UI will not be able to be interacted with until you submit a schema and mapping to the "mapping" endpoint above. So submit a schema and mapping during the startImport extension callback or in the Configure App Modal UI.

With the schema and mapping submitted, the next step would be to implement the startImport extension point that will run when Import data button is clicked. This code should fetch data from a third party source and push to the Import Asset APIs.

When this is all done you can set your status to Ready with the importStatus extension point, causing the Import data button to be active, as shown below.

1
2
   const importStatus = async (context) => {
       console.log("import with id ", context.importId + " sending import status");

       return {
           status: "READY"
       };
   };

We recommend following the guide here to be able to import data into Assets.

Close the tunnel and deploy the app

After confirming the app works locally, deploy the app so that it continues to work when you close the tunnel.

  1. Close your tunnel by pressing Ctrl+C.
  2. Deploy your app by running:
    1
    2
    forge deploy
    

That’s it. You've built an app that retrieves the contents of a page, counts the number of macros, then displays the result in a modal dialog.

Next steps

Check out an example app, continue to one of the other tutorials, or read through the reference pages to learn more.

  • See Example apps for a collection of apps we've built.
  • See the reference pages to learn what else you can do with what you’ve learned.

Rate this page: