Skip to main content

Custom File Transfer

Leverage JupiterOne's Custom File Transfer to ingest assets into JupiterOne and designate the asset's relationships prior to uploading. This integration allows you to import a batch of assets and relationships via CSV file and track and manage each upload within the integration's instances.

You will need to have your assets and relationships in CSV format, and there is a size limitation of 100MB per file. For larger uploads, see our API documentation.

Configuring the integration​

Navigate to the Integrations tab in JupiterOne and select Custom File Transfer. Click New Instance to begin configuring the integration.

For this integration, you will need to have your CSV dataset ready to imported.

Creating a Custom File Transfer instance​

Provide the following when creating an instance for your custom file transfer:

  • The Account Name used to identify the account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Enter the Dataset Name. For the first example data set, use: EuropaUsers

  • Define he Entity Key Property. This is found in the data file. For CSVs, it is the column header. This value should be unique across the entire dataset.

  • Add the Entity Type. This will identify the specific type of entity to be created.

  • Select the Entity Class. This value represents the class of data found in the dataset.

info

For more information about JupiterOne _type and _class values, see our JupiterOne data model.

At this point, the integration is able to upload and ingest the defined dataset into your account. Press Create to create the instance and upload your CSV file.

If you wish to add additional datasets, press the Add Dataset button.

Additionally, you can add Direct and Mapped Relationships by selecting the respective Add relationship button. You can find additional information on adding relationships below.

Adding another data set:​

  • Enter the Dataset Name, the Entity Key Property, and Entity Type.

  • Select the Entity Class.

Defining Relationships​

When uploading your file, you can additionally define both direct and mapped relationships for the dataset.

When defining a relationship, FORWARDS represents source -> target, and REVERSE represents source <- target (target -> source).

This determines the relationship between the entities and which direction the arrow points between them, allowing for illustrating ingress and egress accordingly.

To define direct relationships:​

Press Add Relationship under Direct Relationships and provide the following:

  • The Source Property. The source property indicates what value in the dataset references the target dataset.
  • The Relationship Class
  • The Target Dataset Name. This needs to exactly match the inputted value for the target Dataset Name.
  • The Target Property. The target property indicates what value in the dataset that should be referenced by the source dataset.

Define Mapped Relationships​

Mapped relationships can be defined similarly to direct relationships.

To define the mapped relationships:​
  • Select the Relationship Class.
  • Specify the Direction.
  • Enter the Target Entity Type. :::note To see what _types are available in your account, consider running this J1QL query in your account: FIND * AS e RETURN count(e), e._type. For this tutorial, use: _githubuser :::

Add Field Mappings​

Enter the Source Property and Target Property as desired.

Finalize the integration instance​

Click Create once all values are provided to finalize the integration. You will then be prompted to upload your CSV files.

Custom file transfer example​

To understand how to set up this integration, the following dataset will be used for a tutorial.

Imagine you want to add User and User Group data from your HR software, called Europa, into JupiterOne.

Here are the two example datasets:

  1. Europa Users (europaUsers.csv) Id Name Username Email GroupId 1 Jane jane.c jane.c@company.com A 2 Juan juan.d juan.d@company.com B 3 Julie julie.e julie.e@company.com C

  2. Europa User Groups (europaUserGroups.csv) Id Name A Marketing B Sales C Engineering

We can represent both the Europa Users and Europa Groups as assets in the JupiterOne graph.

Further, we can use the native relationship between the Europa Users GroupId property and the Europa Groups Id property to define a direct relationship between the two datasets in this integration.

Finally, if we want, we could also use the Europa Users Email property to define a mapped relationship to any other data that exists in your JupiterOne account.

Define Datasets​

  • Enter the Dataset Name as: EuropaUsers
  • Enter the Entity Key Property. For this tutorial the first column header of the Europa Users dataset we'll use is: Id
  • Enter the Entity Type as: europa_user.
  • Set the Entity Class as: User.

At this point the integration is able to upload and ingest the Europa Users dataset into your account. With the goal of adding Users Groups and relationships, let's keep going:

  • Press the Add Dataset button
  • Enter the Dataset Name. For the second dataset: EuropaUserGroups
  • Enter the Entity Key Property. For this tutorial we will use the Id column which represents a unique id for each entity.
  • Enter the Entity Type. For the second dataset: europa_user_group
  • Select the Entity Class. For the second: UserGroup

Excellent! Both datasets are now defined.

Define the direct relationship​

The following steps will define the relationship to be built between Users (the source dataset) and User Groups (the target dataset).

    User (source) <--HAS-- User Group (target)
    EuropaUsers.GroupId == EuropaUserGroups.Id

The following steps will build the above relationship:

  • Press Add Relationship under Direct Relationships and
  • Enter the Source Property. For this tutorial, useGroupId as the source property. It is found in EuropaUsers and references the Europa User Groups dataset.
  • Select the Relationship Class. For this tutorial: Has
  • Select the Direction. For this tutorial: REVERSE
  • Enter the Target Dataset Name. For this tutorial: EuropaUserGroups
  • Enter the Target Property. For this tutorial, Id is the target property, found in EuropaUserGroups. Enter Id for this field.

Define Mapped Relationship​

The following steps will define the relationship to be built between EuropaUsers and existing data in your account.

  • Select the Relationship Class. For this tutorial, use: Is
  • Select the Direction. For this tutorial, use: FORWARD
  • Enter the Target Entity Type. For this tutorial, we want to map Europa Users to GitHub Users by matching on their emails. The entity type for GitHub Users is github_user. For this tutorial, use: github_user

Add Field Mappings: Enter the Source Property. For this tutorial, use: Email Enter the Target Property. The GitHub user entity use email as the property name. For this tutorial, use: email

And that's it! Click create to finalize the integration instance and upload the CSV files should you wish.

Next steps​

Now that your integration instance has been configured, it will begin running the transfer, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.

Contents