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

To define a request, decide which mutation endpoint to use. Then, define the content as a list in the parameter. The data structure and content correspond to the FA importing syntax (for details, see the Importing section in FA Back reference). Define attributes without a prefix used in FA importing. For example, the prefix for contacts is "c" and contact name in FA importing is defined as "c.name". However, in the mutation API, the prefix is left out and the attribute is only called 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": ""
      }
    ]
  }
}