Skip to main content

Crawler Import Service

Description

This service is used to simplify importing Atollon data. In Atollon, it's possible to add more complex business logic based on request type and it's parameters. External developers are let go of understanding Atollon blackbox.

Request

POST https://<HOST>/crab/import-tool/<request_type>?instance=<instance_name>

Contact

Create contact (person or company) with (optionally) contact folder identified by context category (FPATypeCategory).

Request

POST https://<HOST>/crab/import-tool/contact?instance=<instance_name>

Data in JSON format:

{
   "person": {
      "firstName":"<name>",
      "lastName":"<surname>",
      "companyPersonRelation": [
        {
         "companyOldId":"<Company old ID>",
         "positionDesc":"<Position of person in company>",
         "companyName":"<Name of the related company>"
        }
      ]
   },
   "company": {
      "companyName": "<company name>"
   },
   "address": [
      {
         "street": "<street + number>",
         "city": "<city name>",
         "zip": "<zip text>",
         "region": "<region name>",
         "country": "<country name>",
         "addressType": "<address type1>"
      },
      {
         "street":"<street + number>",
         "city":"<city name>",
         "zip":"<zip text>",
         "region":"<region name>",
         "country":"<country name>",
         "addressType":"<address type2>"
      }
   ],
   "contacts": {
      "email": [
         {
            "contact": "<email1>",
            "contactInfoTypeName": ""
         }, {
            "contact": "<email2>",
            "contactInfoTypeName": ""
         }
      ],
      "phone": [
         {
            "contact": "<telefon1>",
            "contactInfoTypeName": ""
         }, {
            "contact": "<telefon2>",
            "contactInfoTypeName": ""
         }
      ],
      "mobile": [
         {
            "contact": "<mobil1>",
            "contactInfoTypeName": ""
         }, {
            "contact": "<mobil2>",
            "contactInfoTypeName": ""
         }
      ],
      "web": [
        {
            "contact": "<web1>",
            "contactInfoTypeName": ""
         }, {
            "contact": "<web2>",
            "contactInfoTypeName": ""
         }
      ]
   },
   "description": "<Contact text field>",
   "contactGroup": [
      "<Group 1>",
      " <Group 2>"
   ],
   "contactFolderCategory": [
      "<string1>",
      "<string2>"
    ],
   "externalId": [
     {
      "system": "<system1>",
      "id": "<Contact old id>"
   	 }, {
      "system": "<sytem2>",
      "id": "<Contact old id>"
   	 }
   ],
   "regNo": "<registered number of business>",
   "vatNo": "<VAT number>",
   "trackingCode": "<string>",
   "source": "<original - your system ident>"
}
Response

on SUCESS

  • contactId
  • folderId
  • contact.oldID

Function progress

  • When above request is sent, new TIF is created (TIF = Temporary Import File) and the contents is saved in TIF; TIF type = contact
  • Contact form that is not processed has TIF.status = 1
  • The plugin calls auto-processing that makes the following steps:
    • Person is filled? => lead is "Person contact" (and the person is representative of the company), otherwise it's "Company contact" (either company or person name is required)
Company contact
  • Check whether company is existing (company name matches some record in DB) // see: https://help.atollon.com/books/backend-development/page/modcontact#bkmrk-%C2%A0
  • If company does not exist, create new contact (company)
  • Contact info and address is stored with company contact
  • With company contact id, check whether contact has the desired contact folder. Desired contact folder is folder with FPATypeCategory of the client, lead, supplier, partner, etc. folder types. If the lead folder does not exist, it is created.
  • If contactFolderCategory is not filled-in, the contact folder is not created.
  • contactGroup - find the contact group with the same name. If the contact group does not exist, create it. Assign the contact to the group
Person contact
  • Check whether person is existing (based on e-mail, mobile / if these are not filled-in, the person is created anyway). E-mail and mobile is stored with person contact
  • Contact info and address is stored with person contact
  • With person contact id, check whether contact has the desired contact folder. Desired contact folder is folder with FPATypeCategory of the client, lead, supplier, partner, etc. folder types. If the lead folder does not exist, it is created.
  • If contactFolderCategory is not filled-in, the contact folder is not created.
  • contactGroup - find the contact group with the same name. If the contact group does not exist, create it. Assign the contact to the group
  • employer - if company oldId is found in companyPersonRelation, make binding, otherwise if companyName is filled-in in companyPersonRelation, company based on it's name or create new company contact and create binding

After the request is imported successfully, change the TIF status to "2".

Creating contact folder (client, supplier, etc.)

Contact folders is main building block in contact relations (ATOLLON's context).

Some useful context categories for contact folders used:

Client com.atollon.project.fpatypecategory.client
Supplier com.atollon.project.fpatypecategory.supplier
Lead (potential client) com.atollon.leads.fpatypecategory.lead
Partner com.atollon.project.fpatypecategory.partner

Product

https://<HOST>/crab/import-tool/product?instance=<instance_name>

POST data in JSON format:

{
    "name": "<Product name>",
    "refId": "<Product code>",
    "description": "<Product description>",
    "typeName": "<Product typee = Product, Service, Technology ...>",
    "defaultQuantity": 1.00,
    "unitPrice": 4990.00,
    "unitPriceCurrencyName": "<CZK, USD, etc.>",
    "statusName": "<Product status = Active, Inactive>",
    "unitsName": "<Product units = ks, md, hrs>",
    "vatRateName": "<15 %, 21%, etc.>",
    "openingBalanceQty": 0.00,
    "openingBalanceDate": "<2022-09-09T10:10>" // <now> datetime is default, if not provided,
    "externalId": [
       {
        "system": "<system1>",
        "id": "<ABCD-EFGH-ijkl-...>""
       }, {
        "system": "<sytem2>",
        "id": "<ABCD-EFGH-ijkl-...>""
       }
     ]
}
Response

on SUCCESS

  • productId
  • productName
  • productRefid
Function progress
  • Find product based on it's code + product name, if this does not match, create product
  • If existing product is found, values are updated, ie openingBalanceQty

Activity Billing

To export service activities that include billing items, get the following resource:

Request

GET https://<HOST>/crab/import-tool/activity-billing?billingStatus=toBeInvoiced&instance=<instance_name>

Response
[{
    "activity": {
        "name": "<Activity name>",
        "refId": "<Activity REF ID>",
        "statusName": "<Activity custom status name>",
        "description": "<Activity notes>",
        "created": "<2022-09-01T00:00>",
        "modified": "<2022-09-14T10:00>"
    },
    "project": {
        "name": "<Project name>",
        "refId": "<Project REF ID>"
    },
    "folder": {
        "name": "<Folder name>",
        "refId": "<Folder REF ID>",
        "contactOldId": "<Folder contact old id>"
    },
    "billingItems": 
  		[{
        "productName": "<Product name1>",
        "productRefid": "<Product code>",
        "name": "<Billing item text>",
        "description": "<Billing item description>",
        "quantity": "<1, 0.3, 4, ...>",1.00,
        "unitPrice": "<1, 0.3, 4, ...>",1000.00,
        "currency": "<EUR, CZK, ...>",
        "billingDate": "<2022-09-14T10:00>"
        }, {
        "productName": "<Product name2>",
        "productRefid": "<Product code>",
        "name": "<Billing item text>",
        "description": "<Billing item description>",
        "quantity": "<1, 0.3, 4, ...>",1.00,
        "unitPrice": "<1, 0.3, 4, ...>",1000.00,
        "currency": "<EUR, CZK, ...>",
        "billingDate": "<2022-09-14T10:00>"
    	}, ...],
    "documents": 
        [{
        "name": "<Document name>",
        "url": "<url>"
    	}, {
        "name": "<Document name2>",
        "url": "<url>"
    	}, ...]
}]

Update activity status

Run after you have processed the billing items from activity.

Request

PUT https://<HOST>/crab/import-tool/activity-billing-status?instance=<instance_name>

DATA:

{
    "activity": {
  	    "refId":"<Activity ref. id>",
        "statusName":"Billed"
    }
}

 

Back to top