Skip to main content

Import and modify data via mutation API

Overview

You can import or modify FA data via GraphQL mutation API. When you import an object (for example, a contact or a portfolio), you need to provide all required fields as a parameter. When modifying an object you need to give minimum information that is enough to identify the entity. Imported attributes are updated, the left out attributes keep their previous values.

To import or modify different object types, use the following endpoints:

  • Contacts => importContacts

  • Portfolios => importPortfolios

  • Securities => importSecurities

  • Transactions => importTransactions

  • Trade orders => importTradeOrders

  • Security prices => importPrices

You can adjust the import behavior by using importGeneral endpoint and specifying the import parameters as you need. The import parameters are listed below:

  • importGeneral:

    • rows : list of objects to import (mandatory)

    • withRules : boolean whether to run rules when importing (default = false)

    • importAsync : boolean whether to use asynchronous importing or not (default = false)

    • mode / sMode / pMode / prMode / trMode / oMode / cMode : option to control import behavior for all object types (mode) or specific object type (sMode / pMode / prMode / trMode / oMode / cMode). Available options are:

      • 0 - insert and update (default)

      • 1- insert only

      • 2 - update only

Each endpoint can be used to import or update one or many objects in one request. The response identifies if the request was successful or if it had errors (specified in the response).

Define the request

For a valid request such as below, you need to:

  • Define the mutation endpoint to use.

  • Define all required fields as attributes, as described in FA importing formats. In the request below, for example, the required fields for importing contacts are "Contact ID", "Name", "Type", "Juridical form", "Status", "Tax country", "Classification", and "Identity" (see File format for importing contacts in FA Back reference).

Note

You need to define the request content as a list in the parameter with the syntax from FA importing (see Importing in FA Back reference). However, you need to define the attributes without the prefix used in FA importing. For example, in FA importing, contact name is defined as "c.name", so in the mutation API, you need to define this attribute as "name".

mutation {
  importContacts(contactList: [
    {
      contactId:"GQL1",
      name:"GraphQL contact",
      type:"1",
      taxCountry:"FI",
      juridical:"PE",
      status:"A",
      classification:"PROF",
      identity:"ID"
    }, {
      ....
    }, 
      ...
  ])
}

You can find an example of how to use importGeneral to control whether to run rules in Import data and trigger a business rule.

Interpret the response

The response structure is similar to the request. The result contains a list of map structures. Each item in the list presents an object that was imported. All attributes including the ones not explicitly used in the request are returned. The attributes are prefixed. For example, contact name is c.name. The success is indicated in the importStatus attribute with the OK value.

{
  "data": {
    "importContacts": [
      {
        "c.marketingCommunication": "",
        "c.subType": "",
        "c.language": "",
        "c.type": "1",
        "c.taxCountry": "FI",
        "c.externalId": "",
        "c.memo": "",
        "c.country": "",
        "c.phone2": "",
        "c.phone1": "",
        "c.juridical": "PE",
        "c.representatives": "*** ,",
        "c.fax": "",
        "c.email": "",
        "c.extContactIdList": "",
        "c.name": "GraphQL contact",
        "c.status": "A",
        "c.profileAttributes": "",
        "c.classification3": "",
        "c.contactExchanges": "",
        "importStatus": "OK",
        "c.electronicCommunication": "",
        "c.classification2": "",
        "c.transactionExtIdLevel": "1",
        "c.address1": "",
        "c.address2": "",
        "c.tags": "",
        "c.nationality": "",
        "c.city": "",
        "c.classification": "PROF",
        "c.contactId": "GQL1",
        "c.identity": "ID",
        "c.zipCode": ""
      },...
  ]
}
    

If required attributes are missing or the code is incorrect, the importStatus attribute has the ERROR value. Each attribute with an error is marked with ERROR (ERROR:[ImportError.required] in case the required value is missing).

{
  "data": {
    "importContacts": [
      {
        "c.marketingCommunication": "",
        "c.subType": "",
        "c.language": "",
        "c.type": "1",
        "c.externalId": "",
        "c.taxCountry": "ERROR:[ImportError.required]",
        "c.memo": "",
        "c.country": "",
        "c.phone2": "",
        "c.phone1": "",
        "c.juridical": "ERROR:[ImportError.required]",
        "c.representatives": "*** ,",
        "c.fax": "",
        "c.email": "",
        "c.extContactIdList": "",
        "c.name": "GraphQL contact",
        "c.status": "ERROR:[ImportError.required]",
        "c.profileAttributes": "",
        "c.classification3": "",
        "c.contactExchanges": "",
        "importStatus": "ERROR",
        "c.electronicCommunication": "",
        "c.classification2": "",
        "c.address1": "",
        "c.address2": "",
        "c.tags": "",
        "c.nationality": "",
        "c.city": "",
        "c.classification": "ERROR:[ImportError.required]",
        "c.contactId": "GQL2",
        "c.identity": "ERROR:[ImportError.required]",
        "c.zipCode": ""
      }
    ]
  }
}
In this section: