# Sansan Import Integration You can import business cards that you have created into [Sansan](https://www.sansan.com/) to categorized them. You can also import business cards with attached tag names. ## Prerequisites - Basic knowledge of Treasure Data, including experience using [TD Toolbelt](https://toolbelt.treasuredata.com/). - A Sansan API key - Authorized Treasure Data account access ## Obtaining Sansan API Key Information To obtain a Sansan API key: 1. Login to Sansan then select Settings.![](/assets/image-20191021-140109.d3ea4b5511790f192ecfe064c580d3c80e1d4a3f1e4ecd084ac92e5d31c3765d.b88a27e1.png) 2. From navigation bar on the Settings page, select **API Key** and then copy API Key. ![](/assets/image-20191021-140120.a0e50a1b93894dc4312aaca8eacf406dc054f6af3dc50ff6e851d9ca45b738f4.b88a27e1.png) ## Using the TD Console to Create Your Connection To create a Sansan  connection in TD Console: 1. Open TD Console. 2. Navigate to **Integrations Hub** >  **Catalog**. 3. Click the search icon on the far-right of the Catalog screen, and enter **Sansan**. 4. Hover over the Sansan  connector and select Create Authentication.![](/assets/sansan.57d1108388d3e36dedb1af1f13a2762cc1c5eb9ac151d4a03563764947005b4e.b88a27e1.png) 5. Select **Create Authentication**. The New Authentication dialog opens. ![](/assets/sansannewauth.3842debd43d132771f26b9f5ea5c1d5f39c971e03637d91d57d4f19acc031ddb.b88a27e1.png) 6. Enter your Sansan API Key. 7. Select **Continue**. 8. Enter a name for the Sansan connection. 9. Select **Done**. ## Use TD Console ### Create a Authentication To create an authentication for the Sansan connection: 1. From the TD Console, navigate to **Integrations Hub** >  **Authentications**. 2. Click the search icon on the far-right of the screen, and enter **Sansan**. ![](/assets/sansanauth.5fbf66e4978a09dfcf84b301046d0d5edad3daf08790ae164fb32fe56a7cfa3b.b88a27e1.png) 1. Select **New Source**. The Create Source dialog displays. The dialog contains the following pages: - Connection - Source Table - Data Settings - Data Preview - Data Placement Provide details for the source on each of the pages. ### Connection - **Data Transfer Name** - Enter a name. ### Source Table - **Data Type** — Select Business Card or Tag. *Tag* - **Tag Range** — select a All or Me. - *Business Card* - **Import a set of business cards based on** — Select Term or Condition. Select Term to import cards updated within a specified timeframe. Select Condition to import cards based on specified Tag Names. - **Include previous business card information** — Include past business cards. Check this box if you want business cards, that are recognized as for the same person, to be imported as separate cards. - **Include Tags?** — Import business cards with assigned tags. Check this box if you want the tags to be included in the business cards data. - **Filter by range of holder**:  — The range of business cards can be specified as “me” (only the cards held by oneself) or as “all” (all the cards within the range that can be viewed by oneself). *Term* - **Data Card Updated From** — Import business cards updated since this time. Time is set in UTC. - **Data Card Updated To** — Import business cards updated until this time. Time is set in UTC. - **Incremental** — When importing based on a schedule, the time window of the fetched data automatically shifts forward on each run. For example, if the initial config is January 1, with ten days in duration, the first run fetches data modified from January 1 to January 10, the second run fetches from January 11 to January 20, and so on. *Condition* - **Filter by Tag**: Import business cards contain a Tag. Select this if you want to import by Tag. If you select you must specify a Tag name. Leave the box unchecked if you don't want to match business cards by tags. - **Tag Name**: Import business cards that have the attached tag name specified. Enter only one name. Example: If you enter 'Treasure_Data', all business cards that contain the Treasure_Data tag name are imported. - **Tag range**: Specify the range of Tag holders. Import business cards that have an attached tag within the range of Me or All. ### Data Settings - Page size. Determines the number of records that will be returned for each call to the Sansan REST API. ``` Type: number Default: 300 ``` - Maximum retry times. Specifies the maximum retry times for each API call. ``` Type: number Default: 3 ``` - Initial retry interval millisecond. Specifies the wait time for the first retry. ``` Type: number Default: 20000 ``` - Maximum retry interval milliseconds. Specifies the maximum time between retries. ``` Type: number Default: 120000 ``` ### Data Preview You can see a [preview](/products/customer-data-platform/integration-hub/batch/import/previewing-your-source-data) of your data before running the import by selecting Generate Preview. Data preview is optional and you can safely skip to the next page of the dialog if you choose to. 1. Select **Next**. The Data Preview page opens. 2. If you want to preview your data, select **Generate Preview**. 3. Verify the data. ### Data Placement For data placement, select the target database and table where you want your data placed and indicate how often the import should run. 1. Select **Next.** Under Storage, you will create a new or select an existing database and create a new or select an existing table for where you want to place the imported data. 2. Select a **Database** > **Select an existing** or **Create New Database**. 3. Optionally, type a database name. 4. Select a **Table**> **Select an existing** or **Create New Table**. 5. Optionally, type a table name. 6. Choose the method for importing the data. - **Append** (default)-Data import results are appended to the table. If the table does not exist, it will be created. - **Always Replace**-Replaces the entire content of an existing table with the result output of the query. If the table does not exist, a new table is created. - **Replace on New Data**-Only replace the entire content of an existing table with the result output when there is new data. 7. Select the **Timestamp-based Partition Key** column. If you want to set a different partition key seed than the default key, you can specify the long or timestamp column as the partitioning time. As a default time column, it uses upload_time with the add_time filter. 8. Select the **Timezone** for your data storage. 9. Under **Schedule**, you can choose when and how often you want to run this query. #### Run once 1. Select **Off**. 2. Select **Scheduling Timezone**. 3. Select **Create & Run Now**. #### Repeat Regularly 1. Select **On**. 2. Select the **Schedule**. The UI provides these four options: *@hourly*, *@daily* and *@monthly* or custom *cron*. 3. You can also select **Delay Transfer** and add a delay of execution time. 4. Select **Scheduling Timezone**. 5. Select **Create & Run Now**. After your transfer has run, you can see the results of your transfer in **Data Workbench** > **Databases.** ## Using Command Line to Create Your Sansan Connection You can use the TD Console to configure your connection: 1. Install the latest [Treasure Data Toolbelt](https://toolbelt.treasuredata.com/). 2. Create a configuration file "load.yml" The configuration file includes an in: section where you specify what comes into the connector from Sansan and an out: section where you specify what the connector puts out to the database in Treasure Data. For more details on available out modes, see the Appendix. The following example shows how to specify the import of Business Cards based on a specified Term, without incremental scheduling. ```yaml in: type: sansan api_key: "api key" target: bizcard query_by: "term" biz_range: "all" include_prev_card: true include_tags: true out: mode: append ``` The following example shows how to specify the import of Business Cards based on a specified Term, with incremental scheduling. ```yaml in: type: sansan api_key: "api key" target: bizcard query_by: "term" biz_range: "all" include_prev_card: true  include_tags: true  updated_from: "2018-11-01T00:00:00.000Z" updated_to: "2018-11-12T00:00:00.000Z" incremental: true out: mode: append ``` The following example shows how to specify the import of Business Cards based on a specified Condition without a Tag filter. ```yaml in: type: sansan api_key: "api key" target: bizcard query_by: "condition" biz_range: "all" include_prev_card: true  include_tags: true out: mode: append ``` The following example shows how to specify the import of Business Cards based on a specified Condition with a Tag filter. ```yaml in: type: sansan api_key: "api key" target: bizcard query_by: "condition" biz_range: "all" include_prev_card: true  include_tags: true  gbiz_tag_filter: true biz_tag_name: "tag name" biz_tag_range: "all" out: mode: append ``` The following example shows how to specify the import of Tags only. ```yaml in: type: sansan api_key: "api key" target: tag tag_range: "all" out: mode: append ``` ### Previewing the Data to be Imported (Optional) You can preview data to be imported using the command td connector:preview. ``` $ td connector:preview load.yml ``` ### Execute the Load Job You use td connector:issue to execute the job. You must specify the database and table where you want to store the data before you execute the load job. For example, td_sample_db or td_sample_table. ``` $ td connector:issue load.yml \ --database td_sample_db \ --table td_sample_table \ --time-column date_time_column ``` Treasure Data recommends that you specify a --time-column option, because Treasure Data’s storage is partitioned by time. If the option is not given, the data connector selects the first long, or first timestamped column, as the partitioning time. The type of the column, specified by --time-column, must be either of type  long or timestamp type. You can use Preview results to check for the available column name and type. Generally, most data types have a "last_modified_date" column. If your data doesn’t have a time column, you can add the column by using the add_time filter option. See details at [add_time filter](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function) plugin. td connector:issue assumes you have already created a database (e.g. sample_db) and a table (e.g. sample_table). If the database or the table does not exist in TD, td connector:issue will fail. Therefore you must create the database and table manually or use --auto-create-table with td connector:issue to automatically create the database and table. ```  $ td connector:issue load.yml \ --database td_sample_db \ --table td_sample_table \ --time-column date_time_column \ --auto-create-table ``` Finally, from the command line, submit the load job. Processing might take a couple of hours depending on the data size. ## About Scheduled Execution You can schedule periodic data connector execution for periodic Sansan import. Configure your scheduler carefully to ensure high availability. By using this feature, you no longer need a cron daemon on your local data center. Scheduled execution supports configuration parameters that control the behavior of the data connector during its periodic attempts to fetch data from Sansan: - `incremental` This configuration is used to control the load mode, which governs how the data connector fetches data fromintegration based on one of the native timestamp fields associated with each object. - `columns` This configuration is used to define a custom schema for data to be imported into Treasure Data. You can define only columns that you are interested in here but make sure they exist in the object that you are fetching. Otherwise, these columns aren’t available in the result. - `last_record` This configuration is used to control the last record from the previous load job. It requires the object to include a `key` for the column name and a `value` for the column’s value. The `key` needs to match the Sansan column name. ### Creating a Schedule A new schedule can be created using the td connector:create command. This commands requires - the name of the schedule - a cron-style schedule - the name of database where the data will be stored - the name of the table where the data will be stored - the data connector configuration file - The cron parameter accepts these options: '@hourly', '@daily' and '@monthly'. By default, the schedule is set to the UTC timezone. You can set the schedule in a timezone using -t or --timezone option. The --timezone option only supports extended timezone formats like 'Asia/Tokyo', 'America/Los_Angeles', etc. Timezone abbreviations like PST, CST are not supported and may lead to unexpected schedules. **Examples** ``` $ td connector:create \ daily_import \ "10 0 * * *" \ td_sample_db \ td_sample_table \ load.yml ``` TD also recommends that you specify the --time-column option, since Treasure Data’s storage is partitioned by time. ``` $ td connector:create \ daily_import \ "10 0 * * *" \ td_sample_db \ td_sample_table \ load.yml \ --time-column created_at ``` ### Listing the Schedules You can see the list of currently scheduled entries by entering the command td connector:list. ``` $ td connector:list ``` ### Displaying the Schedule Settings and History of Schedules td connector:show displays the schedule details. ``` td connector:show daily_import ```