Atollon API

Overview

Server Side Integration

Atollon provides developers with either full access to server functions using Web Services based on SOAP API or simplified access using REST API for typical integration tasks.

SOAP API

Any web service is described using WSDL. Each of the WSDL files is available at Host location, including CSS formatted version for human reading. Simply enter Host URL with the name of the WSDL file into browser and you may get overview about the functions supported.

Atollon provides access to almost all functions supported by the solution using Web Services.

REST API

For the most common integration tasks, ATOLLON provides also REST API that makes external developer's life easier by hiding some of the internal complexities of platform (that are still accessible by SOAP API).

Documentation to ATOLLON's REST API functions is available on pages of this wiki dedicated to CRAWLER.

Example Connect

Try to access testing sandbox at our vulcano.atollon.com server.

Use QuickLogin function based on definition at https://river.atollon.com/main.wsdl

Parameters
URI: https://river.atollon.com/soap
server: ask us
password: hash5
user: ask us
Demo Credentials

Server:
User:
Pass:

md5 hash

You can generate your own password md5 hash using:

echo -n "password" | md5sum

API Use Cases

You are free to develop any business application / client portal on top of Atollon Server Platform. Applications being developed on top of ASP include usually web integrations of any kind (Web Leads forms, Applicant tracking forms, Projects reporting, client portal, sales automation functions, etc.). The same API is used for Atollon's core products.

Examples

Atollon Web Leads

Atollon Web Services

Web Services Startup

eShop Example

eShop Example

Overview

Using Atollon to bill/invoice eShop purchases

How to use Atollon to quickly send invoices to eShop clients? See the illustration below describing the scheme necessary to adopt when billing from Atollon.

eShopIntegration.png

Used Functions

Functions to create objects:
(there may be some other functions necessary, if listing is required)

eShop Example

Create New Customer (Person)

First create new contact

CreateContact (main.wsdl) Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateContact>
         <server>acme</server>
         <session>6A941A9BC9EBEFAF585A4B936AA958755B1C85E2BD04</session>
     <PERSON>
        <name1>Jack</name1>
        <name3>Buyer</name3>
        <ADDRESSES>
          <ADDRESS>
            <cityName>London</cityName>
            <countryName>United Kingdom</countryName>
            <isPrimary>1</isPrimary>
            <regionName>London</regionName>
            <street>Our Street 10</street>
            <type>132027101</type>
            <zipName>1100</zipName>
          </ADDRESS>
        </ADDRESSES>
        <CONTACTS>
          <CONTACT>
            <content>jackbuyer@gmail.com</content>
            <isMain>1</isMain>
            <isPrimary>1</isPrimary>
            <type>132031101</type>
          </CONTACT>
          <CONTACT>
            <content>33999888</content>
            <isMain>0</isMain>
            <isPrimary>1</isPrimary>
            <type>132035101</type>
          </CONTACT>
          <CONTACT>
            <content>990888333</content>
            <isMain>0</isMain>
            <isPrimary>1</isPrimary>
            <type>132033101</type>
            <typeType>3</typeType>
          </CONTACT>
        </CONTACTS>
        <PERSONINFO>
          <salutation>Dear Adam</salutation>
          <preferedLang>131428101</preferedLang>
        </PERSONINFO>
      </PERSON>
      </wsdl:CreateContact>
   </soapenv:Body>
</soapenv:Envelope>

CreateContact Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateContactResponse>
         <result>OK</result>
         <time>0.08316803</time>
         <newId>139663101</newId>
      </ns1:CreateContactResponse>
   </ns0:Body>
</ns0:Envelope>

Create New Customer Folder

CreateSimpleFolder (project.wsdl) Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateSimpleFolder>
         <server>acme</server>
         <session>6A941A9BC9EBEFAF585A4B936AA958755B1C85E2BD04</session>
      <FOLDER>
        <name>Buyer, Jack</name>
        <organization>130944101</organization>
        <template>139633101</template>
        <contact>139663101</contact>
        <parent>130944101</parent>
      </FOLDER>
      </wsdl:CreateSimpleFolder>
   </soapenv:Body>
</soapenv:Envelope>

CreateSimpleFolder Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateSimpleFolderResponse>
         <result>OK</result>
         <time>0.28198600</time>
         <newId>139676101</newId>
         <TYPE>
            <name>Client</name>
            <guiAction/>
            <id>132716101</id>
            <iType>1</iType>
            <masterProject>0</masterProject>
         </TYPE>
      </ns1:CreateSimpleFolderResponse>
   </ns0:Body>
</ns0:Envelope>

 

eShop Example

Create New Deal

First Create Project Folder

CreateProject (project.wsdl) Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateProject>
        <server>acme</server>
        <session>6A941A9BC9EBEFAF585A4B936AA958755B1C85E2BD04</session>
        <PROJECT>
          <customer>139676101</customer>
          <folder>139676101</folder>
          <invoiceJournal>133150101</invoiceJournal>
          <name>Super Sales</name>
          <projectTemplate>133297101</projectTemplate>
          <provider>132740101</provider>
        </PROJECT>
      </wsdl:CreateProject>
   </soapenv:Body>
</soapenv:Envelope>

CreateProject Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateProjectResponse>
         <result>OK</result>
         <time>0.24983001</time>
         <newId>139704101</newId>
         <TYPE>
            <id>133295101</id>
            <name>Deal</name>
            <masterProject>0</masterProject>
            <guiAction/>
            <iType>2</iType>
         </TYPE>
      </ns1:CreateProjectResponse>
   </ns0:Body>
</ns0:Envelope>

Second Create Billing Item

CreateProjectItem (item.wsdl) Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateProjectItem>
         <server>acme</server>
         <session>6A941A9BC9EBEFAF585A4B936AA958755B1C85E2BD04</session>     
         <ITEM>
           <amount>1234</amount>
           <billingDate>2020-05-14T00:00:00</billingDate>
           <billingStatus>3</billingStatus>
           <totalQuantity>5</totalQuantity>
           <catalogPrice>190</catalogPrice>
           <currency>CZK</currency>
           <item>133629101</item>
           <name>AAA Batteries</name>
           <project>139704101</project>
           <purchasePrice>130</purchasePrice>
           <quantity>5</quantity>
           <totalAmount>6170</totalAmount>
           <totalAmountWithVat>6787</totalAmountWithVat>
           <vatValue>10</vatValue>
           <ratio>100</ratio>
      </ITEM>
      </wsdl:CreateProjectItem>
   </soapenv:Body>
</soapenv:Envelope>

CreateProjectItem Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateProjectItemResponse>
         <result>OK</result>
         <time>0.01379299</time>
         <count>0</count>
         <itemId>139721101</itemId>
      </ns1:CreateProjectItemResponse>
   </ns0:Body>
</ns0:Envelope>
eShop Example

Create New Invoice

Create Invoice from Billing Items in For approval Status

CreateInvoicesFromItems (invoice.wsdl) Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateInvoicesFromItems>
         <server>acme</server>
         <session>6A941A9BC9EBEFAF585A4B936AA958755B1C85E2BD04</session>
         <PROJECTS>
            <RECORD>
               <id>139704101</id>
            </RECORD>
         </PROJECTS>
      </wsdl:CreateInvoicesFromItems>
   </soapenv:Body>
</soapenv:Envelope>

CreateInvoicesFromItems Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateInvoicesFromItemsResponse>
         <result>OK</result>
         <time>0.52524996</time>
         <INVOICE>
            <id>139758101</id>
            <invoiceNumber>232010001</invoiceNumber>
         </INVOICE>
      </ns1:CreateInvoicesFromItemsResponse>
   </ns0:Body>
</ns0:Envelope>
eShop Example

Create Recurring Billing Request

On top of created project (deal), it is possible to create recurring billing request.

See the documentation of CreateFolderItem function for more details.

Example CreateFolderItem (item.wsdl) Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateFolderItem>
         <server>acme</server>
         <session>7CDF678513DCBF0379DDD26A6961B604D7F1515CBD04</session>
         <ITEM>
            <amount>1234</amount>
            <billingDate>2020-05-14T00:00:00</billingDate>
            <billingStatus>2</billingStatus>
            <totalQuantity>5</totalQuantity>
            <catalogPrice>190</catalogPrice>
            <currency>CZK</currency>
            <item>133629101</item>
            <name>Repeated service</name>
            <note>Billing the yearly service.</note>
            <purchasePrice>130</purchasePrice>
            <quantity>5</quantity>
            <folder>139676101</folder>
            <totalAmount>6170</totalAmount>
            <totalAmountWithVat>6787</totalAmountWithVat>
            <vatValue>10</vatValue>
            <ratio>100</ratio>
            <taxationDate>2020-05-14T00:00:00</taxationDate>
            <isModelItem>1</isModelItem>
            <validFrom>2020-05-14T00:00:00</validFrom>
            <validTo>2099-05-04T00:00:00</validTo>
            <destinationProject>139704101</destinationProject>
            <billingFrequency>2</billingFrequency>
         </ITEM>
      </wsdl:CreateFolderItem>
   </soapenv:Body>
</soapenv:Envelope>

CreateFolderItem (Response)

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateFolderItemResponse>
         <result>OK</result>
         <time>0.01345706</time>
         <count>0</count>
         <itemId>139812101</itemId>
      </ns1:CreateFolderItemResponse>
   </ns0:Body>
</ns0:Envelope>
eShop Example

Execute Workflow Actions Immediately

 In case your integration requires executing workflow actions immediately after your request, it is necessary to call CheckWorkflowQueue function that is part of features.wsdl.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CheckWorkFlowQueue>
         <server>yourserver</server>
         <session>---yoursessionstring---</session>
      </wsdl:CheckWorkFlowQueue>
   </soapenv:Body>
</soapenv:Envelope>
eShop Example

Create New Marketing Trigger

Marketing triggers are used to track any activity of the contact / public user, which have some meaning in your company sales or marketing process.

The example below notifies Atollon about new phone number added to contact. Atollon may therefore create call task.

Example Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateMarketingTriggers>
         <server>acme</server>
         <session>61A...DBD04</session>
         <MARKETING_TRIGGER>
            <baseType>new-phone-number</baseType>
            <contextId>132716101</contextId>
            <contactId>139663101</contactId>
            <url>www.yourcompany.com/product/page</url>
            <trackingCode>www.company.com/product/page</trackingCode>
            <description>Extranet user added new phone number</description>
            <triggerDate>2020-07-31 12:00</triggerDate>
            <numberOfVisits>1</numberOfVisits>
         </MARKETING_TRIGGER>
      </wsdl:CreateMarketingTriggers>
   </soapenv:Body>
</soapenv:Envelope>

Example Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateMarketingTriggersResponse>
         <result>OK</result>
         <time>0.22972488</time>
         <newId>400097101</newId>
      </ns1:CreateMarketingTriggersResponse>
   </ns0:Body>
</ns0:Envelope>

Fields Description

Field name Example Description
baseType

new-phone-number

url-visit

goal-achieved

Text identification of the marketing trigger (what actually happened)
contextId 123456789000 Identification of Folder ID, Project ID or Activity ID in Atollon's context structure. It is necessary to enter context ID in case it should be displayed in context Timeline.
contactId 113456789000 Identification of contact, who caused the trigger
url https://yourcompany.atollon.com/pub/23423432 Page that the contact visited (optional)
trackingCode yourSuperCampaignXYZ Any text string representing one particular campaign / marketing activity / message template
description Contact visited URL Any descriptive text that will be visible to Atollon users in Timeline
triggerDate 2020-08-12 12:00 When the trigger happened?
numberOfVisits 45 In case the target user is super active (or robot), we may want to avoid spamming Atollon with unnecessary records and aggregate page visits

User Interface Customization

User Interface Customization

Modules Registry

List of module idents that can be used to store it's own settings (as part of the Features module).

newpioneer=# select * from features_modules ;
    id     |         modulename         |                moduleid
-----------+----------------------------+-----------------------------------------
  97141000 | Atollon Tasks              | com.atollon.scheduler.tasks
  97142000 | Atollon Timesheets         | com.atollon.scheduler.timesheet
  97143000 | Atollon Activity panel     | com.atollon.project.activitypanel
  97144000 | Atollon Views              | com.atollon.features.views
 112099000 | Atollon Task Workflow      | com.atollon.scheduler.workflow.task
 112100000 | Atollon Event Workflow     | com.atollon.scheduler.workflow.event
 112101000 | Atollon Issue Workflow     | com.atollon.scheduler.workflow.issue
 114529000 | Atollon Messages           | com.atollon.messaging.messages
 114533000 | Atollon Contact            | com.atollon.core.contact
 114534000 | Atollon Document           | com.atollon.core.document
 114535000 | Atollon Features           | com.atollon.core.features
 114536000 | Atollon Finder             | com.atollon.core.finder
 114537000 | Atollon Form               | com.atollon.core.form
 114538000 | Atollon Project            | com.atollon.core.project
 114539000 | Atollon User               | com.atollon.core.user
 114540000 | Atollon Budget             | com.atollon.finance.budget
 114541000 | Atollon Invoice            | com.atollon.finance.invoice
 114542000 | Atollon Order              | com.atollon.finance.order
 114543000 | Atollon Item               | com.atollon.finance.item
 114544000 | Atollon Billing            | com.atollon.finance.billing
 114545000 | Atollon Desktop            | com.atollon.lagoon.desktop
 114546000 | Atollon General            | com.atollon.lagoon.general
 114547000 | Atollon TaskBar            | com.atollon.lagoon.taskBar
 114548000 | Atollon Dashboard          | com.atollon.lagoon.dashboard
 114549000 | Atollon MassMessage        | com.atollon.messaging.massMessage
 114550000 | Atollon Applicant          | com.atollon.recruitment.applicant
 114551000 | Atollon Vacancies          | com.atollon.recruitment.vacancies
 114552000 | Atollon Search             | com.atollon.recruitment.search
 114553000 | Atollon Events             | com.atollon.scheduler.events
 114554000 | Atollon Issues             | com.atollon.scheduler.issues
 114555000 | Atollon TSValuation        | com.atollon.scheduler.TSValuation
 114556000 | Atollon Workers            | com.atollon.temporary.workers
 114557000 | Atollon Staffing           | com.atollon.temporary.staffing
 114558000 | Atollon ShiftOrder         | com.atollon.temporary.shiftOrder
 114559000 | Atollon Wage               | com.atollon.temporary.wage
 114560000 | Atollon Advanced TimeSheet | com.atollon.temporary.advancedTimeSheet
 114561000 | Atollon Reporting          | com.atollon.utils.reporting
 114562000 | Atollon Recruitment Search | com.atollon.recruitment.search
 114563000 | Atollon Desktop            | com.atollon.core.desktop
 130388000 | Atollon Scheduler Settings | com.atollon.scheduler.settings
 130389000 | Atollon Items              | com.atollon.item.items
(41 rows)

SOAP UI in Atollon Environment

Run SOAP Query

soapui-new-soap-project.png

soapui-new-soap-project-2.png

soapui-new-soap-project---list-lang.png

Test Automation

Installation

Web Service Exception Listing

name reason code
EX_OK Operation succesfully finished 0
EX_FAIL Operation failed 1
EX_UNKNOWN Unknown exception 2
EX_WARNING Operation finished, but some warnings occured 3
EX_LIST_ITEM_NOT_FOUND Item not found in list 4
EX_ITEM_NOT_FOUND Specified item wasn't found 5
EX_FILE_NOT_FOUND File was not found 6
EX_FILEOPEN_WRITE Unable to open file for writing 7
EX_FILEOPEN_READ Unable to open file for reading 8
EX_NO_MEMORY Not enough memory 9
EX_IO Exception in IO 10
EX_IO_READ Unable to finish IO read 11
EX_IO_WRITE Unable to finish IO write 12
EX_NOT_SUPPORTED Requested operation is not supported 13
EX_INVALID_PARAMETER Given parameter is invalid 14
EX_INVALID_HANDLE Given handle is invalid 15
EX_TOO_MANY_ITEMS There is no space for new item in the list 16
EX_UNLOCK_TO_FOREIGN_LOCK Attempt to unlock item which was not locked by current thread 17
EX_NOT_LOCKED Attempt to unlock item which is not locked 18
EX_NOT_INITIALIZED Attempt to use uninitialized item 19
EX_BAD_TYPE Given paramater has other type then expected 20
EX_BAD_DATA_FORMAT Given data has invalid or bad format 21
EX_TOO_BIG Given parameters are too big 22
EX_INVALID_RESPONSE_FORMAT Retrieved response has invalid format 23
EX_INVALID_XML_FORMAT invalid format of XML data 24
EX_INVALID_REQUEST_FORMAT Retrieved request has invalid format 25
EX_ITEM_STILL_IN_USE Cannot remove item because it is still in use 26
EX_INVALID_LICENCE The licence is invalid, contact your vendor to get new one 27
EX_LICENCE_EXPIRED The licence has expired, contact your vendor to get new one 28
EX_TOO_MANY_USERS The limit of simultaneously connected users (specified in the licence) was reached. 29
EX_SERVER_MODULE_NOT_LOADED Server module not loaded 30
EX_CLIENT_MODULE_NOT_LOADED Client module not loaded 31
EX_ACC_ACCESS_REFUSED Not enough access rights to perform action 65537
EX_ACC_ACL_NOT_FOUND ALC for given handle was not found 65538
EX_ACC_ACCESS_DENIED Bad username and/or password 65539
EX_ACC_SESSION_NOT_FOUND Given session id is invalid 65540
EX_ACC_HANDLE_CYCLIC_DEPENDENCY There is a cyclic dependency between linked handles 65541
EX_MSG_MESSAGES_GROUP_NOT_FOUND Given message group was not found 131073
EX_MSG_ALREADY_APPROVED Given message is already approved 131074
EX_MSG_NO_APPROVAL_PERMISSION Message cannot be approved, you don't have the approve permission 131075
EX_MM_SENT_WITHOUT_STORE Mass mail sent, but not stored 131084
EX_MM_NO_TREENODE No treenode 131085
EX_MM_NO_RECIPIENT No recipient 131086
EX_MM_NO_EMAIL No email 131087
EX_MM_NO_EMAILID No email id 131088
EX_MM_NO_IDENTITY No identity 131089
EX_MM_NO_TEMPLATE No template 131090
EX_MM_NO_DOCTMPFILE No document 131091
EX_MM_EMPTY_DOC Document is empty 131092
EX_MM_FAIL_TRANSFER Transfer failed 131093
EX_MM_FAIL_SOCKET Socket failed 131094
EX_MM_FAIL_POSTQUERY Post query failed 131095
EX_MM_FAIL_GETRESPONSE Get response failed 131096
EX_MM_EXCLUDED Recipient exluded 131097

 

WSDL Listing

Web Service Functions

List of Web Services functions examples and their explanation.

Web Service Functions

CreateFolderItem

Description

Create recurring billing request. Recurring billing request is used to instruct the server to create individual instance of Billing Request, which is a source for Invoice creation. 

Important Parameters

amount Unit price to be charged
billingDate Sample date, in which the Billing Request will be used as a date for invoicing.
billingStatus

1 .. Pending

2 .. For Approval (Sales Order may be generated here)

3 .. To Be Invoiced (Invoice may be generated here)

totalQuantity

Pcs to be charged per Unit price after free Qty is reduced

catalogPrice

Price before any discounts

item

Product ID

name

Main title of the future Billing Request

note

Future description of Billing Request

purchasePrice

Unit price for which the goods is purchased

Quantity

Pcs to be charged per Unit Price

folder

Customer folder ID

totalAmount

total qty * amount

totalAmountWithVat

totalAmount + VAT

vatValue

VAT rate in numbers

ratio

fixed value (100) = 100%

taxationDate

Date relative to Billing Date, in which you may decide to put the transaction into current / previous / next periods. Put any date close to Billing Date (ie any day in the same/previous month)

isModelItem

1

validFrom

Date, from which the rule becomes active. Difference of dates between validFrom and billingDate is important. Item generated in validFrom = today should have billingDate today + 1 year, in case the first next fee is paid after one year of using the service.

validTo

Expiration date

destinationProject

Target Project ID, where the Billing Request will be created.

billingFrequency

2 .. yearly

4 .. quarterly

6 .. monthly

8 .. weekly

10 .. daily

Request Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateFolderItem>
         <server>acme</server>
         <session>7CDF678513DCBF0379DDD26A6961B604D7F1515CBD04</session>
         <ITEM>
            <amount>1234</amount>
            <billingDate>2020-05-14T00:00:00</billingDate>
            <billingStatus>2</billingStatus>
            <totalQuantity>5</totalQuantity>
            <catalogPrice>190</catalogPrice>
            <currency>CZK</currency>
            <item>133629101</item>
            <name>Repeated service</name>
            <note>Billing the yearly service.</note>
            <purchasePrice>130</purchasePrice>
            <quantity>5</quantity>
            <folder>139676101</folder>
            <totalAmount>6170</totalAmount>
            <totalAmountWithVat>6787</totalAmountWithVat>
            <vatValue>10</vatValue>
            <ratio>100</ratio>
            <taxationDate>2020-05-14T00:00:00</taxationDate>
            <validFrom>2020-05-14T00:00:00</validFrom>
            <validTo>2099-05-04T00:00:00</validTo>
            <destinationProject>139704101</destinationProject>
            <billingFrequency>2</billingFrequency>
         </ITEM>
      </wsdl:CreateFolderItem>
   </soapenv:Body>
</soapenv:Envelope>

Response Example

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateFolderItemResponse>
         <result>OK</result>
         <time>0.01345706</time>
         <count>0</count>
         <itemId>139812101</itemId>
      </ns1:CreateFolderItemResponse>
   </ns0:Body>
</ns0:Envelope>
Web Service Functions

UpdateFormItemValues

There are several scenarios to use this function, based on knowledge you have about the form, where you want to save the data.

FormValuesId + formItemName

You may gather formValuesId from context object using get function (getFolder, getProject, getActivity). FormValuesId is bigint which identifies set of values of one form instance.

formItemName is the name of form field. Form fields may be listed using ListFormItem method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:UpdateFormItemValues>
         <server>acme</server>
         <session>....string_here....</session>
         <formValuesId>392302101</formValuesId>
         <ITEMVALUE>
            <formItemName>form-component-name-here</formItemName>
            <value>123456</value>
         </ITEMVALUE>
      </wsdl:UpdateFormItemValues>
   </soapenv:Body>
</soapenv:Envelope>
Web Service Functions

GetDocument

WSDL

document_library.wsdl

Required parameter

Example Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:GetDocument>
         <server>multi</server>
         <session>BDA7025DFBA9CDF53AE306DB4372AF3492FA59DBBD04</session>
         <id>141942102</id>
      </wsdl:GetDocument>
   </soapenv:Body>
</soapenv:Envelope>

Example Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:GetDocumentResponse>
         <result>OK</result>
         <time>0.01405215</time>
         <count>1</count>
         <id>141942102</id>
         <DOCUMENT>
            <folder/>
            <createdByName>AdminAtollon</createdByName>
            <id>141942102</id>
            <acl>DLIB000000008997</acl>
            <name>1PMP-Canvas.pdf</name>
            <description/>
            <descriptionId/>
            <validByDate>0</validByDate>
            <createdBy>133780102</createdBy>
            <fileHandle>2020/06/22/141941102</fileHandle>
            <lang>0</lang>
            <treeHandle>134567102</treeHandle>
            <fileSize>204248</fileSize>
            <printed>0</printed>
            <internalNumber/>
            <barcode/>
            <internalType>3</internalType>
            <fileName>1PMP-Canvas.pdf</fileName>
            <lock>0</lock>
            <deleted>0</deleted>
            <creationDate>2020-06-22T16:27:00</creationDate>
            <lastChangeDate>2020-06-22T16:27:00</lastChangeDate>
            <validFrom>2020-06-22T00:00:00</validFrom>
            <validTo>2020-06-22T00:00:00</validTo>
            <parentName/>
            <originalName/>
            <categoryName/>
            <locationName/>
            <typeName/>
            <storageId>134687102</storageId>
            <storageSubdir/>
            <isInStorage>1</isInStorage>
            <mimeContentType>application/pdf; charset=binary</mimeContentType>
            <contextId>134567102</contextId>
         </DOCUMENT>
      </ns1:GetDocumentResponse>
   </ns0:Body>
</ns0:Envelope>

 

 

Web Service Functions

ListDocument

Function that lists document in given folder. Documents can be stored in most of the folders of tree structure. Therefore any context ID (Folder, Project or Activity) may act as document placeholder = parent

WSDL

document_library.wsdl

Example Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:ListDocument>
      <server>multi</server>
      <session>BDA7025DFBA9CDF53AE306DB4372AF3492FA59DBBD04</session>
      <limit>100</limit>
      <offset>0</offset>
      <parent>134567102</parent>
      <RESTRICTIONS>and aa.doc_parent is null</RESTRICTIONS>
      </wsdl:ListDocument>
   </soapenv:Body>
</soapenv:Envelope>

The restriction means no older document versions would be returned as a result of query.

Example Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:ListDocumentResponse>
         <result>OK</result>
         <time>0.01323104</time>
         <count>1</count>
         <DOCUMENT>
            <folder/>
            <createdByName>AdminAtollon</createdByName>
            <id>141942102</id>
            <acl>DLIB000000008997</acl>
            <name>1PMP-Canvas.pdf</name>
            <description/>
            <descriptionId/>
            <validByDate>0</validByDate>
            <createdBy>133780102</createdBy>
            <fileHandle>2020/06/22/141941102</fileHandle>
            <lang>0</lang>
            <treeHandle>134567102</treeHandle>
            <fileSize>204248</fileSize>
            <printed>0</printed>
            <internalNumber/>
            <barcode/>
            <internalType>3</internalType>
            <fileName>1PMP-Canvas.pdf</fileName>
            <lock>0</lock>
            <deleted>0</deleted>
            <creationDate>2020-06-22T16:27:00</creationDate>
            <lastChangeDate>2020-06-22T16:27:00</lastChangeDate>
            <validFrom>2020-06-22T00:00:00</validFrom>
            <validTo>2020-06-22T00:00:00</validTo>
            <parentName/>
            <originalName/>
            <categoryName/>
            <locationName/>
            <typeName/>
            <storageId>134687102</storageId>
            <storageSubdir/>
            <isInStorage>1</isInStorage>
            <mimeContentType>application/pdf; charset=binary</mimeContentType>
         </DOCUMENT>
      </ns1:ListDocumentResponse>
   </ns0:Body>
</ns0:Envelope>
Web Service Functions

CreateGlobalText

Global texts are used as storage of localizable text blocks, usually used in printing. 

Part of translate.wsdl

LANG must be EN.

Below is the example of Invoice footer print.

Request Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateGlobalText>
         <server>acme</server>
         <session>4D2...D04</session>
         <identification>invoice-footer</identification>
         <LANG>
            <id>131485101</id>
            <value>In case of any questions, or request for additional details, do not hesitate to contact us by email to invoice@company.com or using phone number +44 00099333. Yours sincerely, Your Team.</value>
         </LANG>
      </wsdl:CreateGlobalText>
   </soapenv:Body>
</soapenv:Envelope>

Response Example

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateGlobalTextResponse>
         <result>OK</result>
         <count>0</count>
         <itemId>1936935101</itemId>
      </ns1:CreateGlobalTextResponse>
   </ns0:Body>
</ns0:Envelope>

ListLanguages

Global Text Idents

Below you can find examples of Global text idents that are used mainly as text blocks when printing documents from ATOLLON.

Document Global text IDENT Description
Invoice issued invoice-footer Print text at the bottom of invoice
Estimate estimate-footer Print text at the bottom of estimate
Invoice/estimate/order/offer invoice-global-CSS Use corporate CSS

 

Web Service Functions

CreateMarketingTriggers

Description

Marketing triggers are used to track any activity of the contact / public user, which have some meaning in your company sales or marketing process.

Fields Description

Field name Example Description
baseType

new-phone-number

url-visit

goal-achieved

mail-url-visit

mail-open

url-visit

unsubscribe

Text identification of the marketing trigger (what actually happened)
contextId 123456789000 Identification of Folder ID, Project ID or Activity ID in Atollon's context structure. It is necessary to enter context ID in case it should be displayed in context Timeline.
contactId 113456789000 Identification of contact, who caused the trigger
url https://yourcompany.atollon.com/pub/23423432 Page that the contact visited (optional)
trackingCode yourSuperCampaignXYZ Any text string representing one particular campaign / marketing activity / message template
description Contact visited URL Any descriptive text that will be visible to Atollon users in Timeline
triggerDate 2020-08-12 12:00 When the trigger happened?
numberOfVisits 45 In case the target user is super active (or robot), we may want to avoid spamming Atollon with unnecessary records and aggregate page visits

The example below notifies Atollon about new phone number added to contact. Atollon may therefore create call task.

Example Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateMarketingTriggers>
         <server>acme</server>
         <session>61A...DBD04</session>
         <MARKETING_TRIGGER>
            <baseType>new-phone-number</baseType>
            <contextId>132716101</contextId>
            <contactId>139663101</contactId>
            <url>www.yourcompany.com/product/page</url>
            <trackingCode>www.company.com/product/page</trackingCode>
            <description>Extranet user added new phone number</description>
            <triggerDate>2020-07-31 12:00</triggerDate>
            <numberOfVisits>1</numberOfVisits>
         </MARKETING_TRIGGER>
      </wsdl:CreateMarketingTriggers>
   </soapenv:Body>
</soapenv:Envelope>

Example Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateMarketingTriggersResponse>
         <result>OK</result>
         <time>0.22972488</time>
         <newId>400097101</newId>
      </ns1:CreateMarketingTriggersResponse>
   </ns0:Body>
</ns0:Envelope>

WSDL Listing

web.wsdl

Web Service Functions

NewMail

Description

New mail function is used to send regular e-mail from Atollon. I supports sending both plaintext and html e-mails. In case html e-mail is sent, plaintext part is generated automatically.

Fields Description

Field Description Example
priority E-mail priority handled by other mail clients 1, 2, 3
group Message group with similar characteristics, required

For e-mails sent in context, there is always default "group" available in the response of request to getFolder, getProject, getActivity. For example:

<messageGroup>133185101</messageGroup> 

treeHandle Message container (mailbox)

Similar comment to "group" field above:

<messageDefault>133186101</messageDefault> 

html What is the body format?

0..plaintext

1..html

encoding Use utf-8 only

utf-8

from Full format of sender mailbox

 

to Recipient address

 

subject Subject of the message

 

body Either plaintext or html part of the message (based on above html = 0/1 flag)

 

attachments.attachment Link to documentId in Atollon. The document will be converted to base64 and added to sent e-mail

 

forwardEmails List ids of e-mail messages that will be attached

 

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:NewMail>
         <server>acme</server>
         <session>5B5EA....8BD04</session>
      <mail>
        <priority>2</priority>
        <group>491826101</group>
        <treeHandle>491827101</treeHandle>
        <html>1</html>
        <encoding>utf-8</encoding>
        <from>"Your team" &lt;admin@mydomain.com&gt;</from>
        <to>jan@safka.cz</to>
        <subject>Welcome to your new world of success</subject>
        <body>&lt;html&gt;&lt;head&gt;&lt;title&gt;Welcome to your new world of success&lt;/title&gt; &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt; &lt;style type="text/css"&gt; &lt;!-- body,td,th { font-family: Arial, Helvetica, sans-serif; font-size: 12px; color: #333333; } a:link { color: #666666; } a:visited { color: #999999; } --&gt; &lt;/style&gt;&lt;/head&gt;&lt;body&gt;&lt;div ALIGN="LEFT"&gt;&lt;span style="font-family:helvetica,arial,sans-serif; font-size:12px; color:#000000; "&gt;This is the secret message&lt;/span&gt;&lt;/div&gt;

&lt;br/&gt;

&lt;div ALIGN="LEFT"&gt;&lt;span style="font-family:helvetica,arial,sans-serif; font-size:12px; color:#000000; "&gt;Your super powerful team&lt;/span&gt;&lt;/div&gt;

&lt;/body&gt;&lt;/html&gt;</body>
        <attachments>
          <attachment>
            <documentId>496477101</documentId>
          </attachment>
        </attachments>
        <forwardEmails/>
      </mail>
      </wsdl:NewMail>
   </soapenv:Body>
</soapenv:Envelope>
Response
<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:NewMailResponse>
         <result>OK</result>
         <time>0.07684398</time>
         <newId>496505101</newId>
         <newAcl>MSGS000000151828</newAcl>
         <needApproval>0</needApproval>
      </ns1:NewMailResponse>
   </ns0:Body>
</ns0:Envelope>
Web Service Functions

GetSchedulerSettings

Description

Function that takes care about administration of lists connected with Events (calendar), Tasks and Issues.

Settings are administered using one function only - UpdateSchedulerSettings.

Type of settings
ListType Settings
1 Scheduler status
2 Severity
3 Solution status
4 Type of work
Web Service Functions

CreateProjectItem

Description

Create billing request. Billing request is used as a source for creating new invoice. That invoice can be created manually from Billing Invoices, using Draft Invoice generation or using one-off function CreateInvoicesFromItems. 

Important Parameters

amount Unit price to be charged
billingDate Date, in which the Billing Request will become valid for invoicing.
billingStatus

0 .. Sales Items (representing Deal Value)

 

1 .. Pending

2 .. For Approval (Sales Order may be generated here)

3 .. Approved by manager (Invoice may be generated here, only users with Authorize rights to project may approve billing items)

4 .. Billed
5 .. Approved by client

6 .. Postponed

7 .. Canceled

 

999 .. Installed technology project items // will be canceled

type

1 .. sales items or billing items

2 .. auto-generated time sheet item

3 .. installed technology

catalogPrice

Price before any discounts (also referred as Recommended Price, Price List Price, ...). The original price, from which discount is calculated.

item

Product ID

name

Main title of the Billing Request

note

Description of Billing Request

purchasePrice

Unit price for which the goods is purchased

quantity

Pcs to be charged per Unit Price

folder

Customer folder ID

totalAmount

qty * amount

totalAmountWithVat

totalAmount + VAT

vatValue

VAT rate in numbers

ratio

fixed value (100) = 100% (used only in sales opportunity/deal to evaluate probability of the item in the sales basket)

project

Project ID, where the Billing Request will be created.

Request Example

CreateProjectItem (item.wsdl) Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:CreateProjectItem>
         <server>acme</server>
         <session>6A941A9BC9EBEFAF585A4B936AA958755B1C85E2BD04</session>     
         <ITEM>
           <amount>1234</amount>
           <billingDate>2020-05-14T00:00:00</billingDate>
           <billingStatus>3</billingStatus>
           <totalQuantity>5</totalQuantity>
           <catalogPrice>190</catalogPrice>
           <currency>CZK</currency>
           <item>133629101</item>
           <name>AAA Batteries</name>
           <project>139704101</project>
           <purchasePrice>130</purchasePrice>
           <quantity>5</quantity>
           <totalAmount>6170</totalAmount>
           <totalAmountWithVat>6787</totalAmountWithVat>
           <vatValue>10</vatValue>
           <ratio>100</ratio>
      </ITEM>
      </wsdl:CreateProjectItem>
   </soapenv:Body>
</soapenv:Envelope>

CreateProjectItem Response

<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://atollon.com/enterprise/wsdl">
   <ns0:Body>
      <ns1:CreateProjectItemResponse>
         <result>OK</result>
         <time>0.01379299</time>
         <count>0</count>
         <itemId>139721101</itemId>
      </ns1:CreateProjectItemResponse>
   </ns0:Body>
</ns0:Envelope>
Web Service Functions

ListLanguages

Part of translate.wsdl

Sample Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:ListLanguages>
         <server>saas</server>
         <session>FB...C3</session>
      </wsdl:ListLanguages>
   </soapenv:Body>
</soapenv:Envelope>

Sample Response

Reduced to one item.

         <LANGUAGE>
            <charset>iso-8859-2</charset>
            <id>2607000</id>
            <languageLong>Czech</languageLong>
            <languageShort>CZE</languageShort>
            <isoShort>cz</isoShort>
            <alternativeShort/>
            <priority>0</priority>
            <useForTranslate>1</useForTranslate>
            <useForWeb>1</useForWeb>
         </LANGUAGE>

 

Web Service Functions

ListContactList

Description

Function listing basic contact configuration items / lists.

Important Parameters

list

contacttype

industry

nationality

companylegalform

category

department

position

addresstype

relationtype_p (person)

relationtype_c (company)

treeHandle

either use "node" attribute from Login function, DEFAULTS->DEFAULT with "ident" CONTACTCONFIGNODE or use attrib useDefaultTreeHandle = true

   

Request Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://atollon.com/enterprise/wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <wsdl:ListContactList>
         <server>atollon</server>
         <session>4A...04</session>
         <treeHandle>1685000</treeHandle>
         <list>contacttype</list>
      </wsdl:ListContactList>
   </soapenv:Body>
</soapenv:Envelope>

Response Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
      <atollon:ListContactListResponse xmlns:atollon="http://iterity.com/enterprise/wsdl">
         <result>OK</result>
         <time>0.01314497</time>
         <count>12</count>
         <ITEM>
            <id>1883000</id>
            <name>E-mail (other)</name>
            <type>1</type>
         </ITEM>
         <ITEM>
            <id>1884000</id>
            <name>E-mail (personal)</name>
            <type>1</type>
         </ITEM>
         <ITEM>
            <id>1885000</id>
            <name>E-mail (work)</name>
            <type>1</type>
         </ITEM>
         ...
      </atollon:ListContactListResponse>
   </soapenv:Body>
</soapenv:Envelope>

 

Web Service Functions

ModifyProjectItemValues

8 metod nastavení cen položek kufříku

SetPurchaseByMargin: purchase_price = amount x (1 - value)
SetSalesByMargin: amount = purchase_price/ (1 - value)
SetPurchaseByPurchase: purchase_price=purchase_price*(value/sum(purchase_price*quantity))
SetPurchaseBySales: purchase_price=amount*(value/sum(amount*quantity))
SetPurchaseByQuantity: purchase_price=(value/sum(quantity))
SetSalesBySales: amount=amount*(value/sum(amount*quantity))
SetSalesByPurchase: amount=purchase_price*(value/sum(purchase_price*quantity))
SetSalesByQuantity: amount=(value/sum(quantity))
Web Service Functions

CreateEvent

WSDL

scheduler.wsdl

GetSchedulerSettings

Contains several configurations of lists, incl. Solution Status and Type of Work (entryType) used in creating New Event. Please note that Solution Status should be selected based on Type of work and current user's profile.

Example Request

Operation request: 'CreateEvent'
<persistency-request operationId='CreateEvent'>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <ns1:CreateEvent xmlns:ns1="http://atollon.com/enterprise/wsdl">
      <server>acme</server>
      <session>...</session>
      <ITEM>
        <chargeable>0</chargeable>
        <remoteHeadId>0</remoteHeadId>
        <remoteId>0</remoteId>
        <resourceId>0</resourceId>
        <status>0</status>
        <userId>//--ID of event owner-user--//</userId>
        <completed xsi:nil="true"/>
        <multiEventTask>0</multiEventTask>
        <forUser>//--ID of event owner-user--//</forUser>
        <location>Event location text</location>
        <iversion></iversion>
        <solutionStatus>//-- ID of custom state--//</solutionStatus>
        <developmentStatus>0</developmentStatus>
        <severity>0</severity>
        <isPrivate>0</isPrivate>
        <activityId xsi:nil="true"/>
        <projectId xsi:nil="true"/>
        <folderId>//-- ID of customer folder--//</folderId>
        <nodeId>0</nodeId>
        <customId>0</customId>
        <comments></comments>
        <reminder>0</reminder>
        <addDuration>0</addDuration>
        <estimationHours>0</estimationHours>
        <actualHours>0</actualHours>
        <milestones>0</milestones>
        <description>Event description text ...</description>
        <htmlText></htmlText>
        <dateTo>2023-03-09T12:30:00</dateTo>
        <dateFrom>2023-03-09T12:00:00</dateFrom>
        <priority>0</priority>
        <entryType>//-- ID of type of work--//</entryType>
        <distributionHandle>//----//</distributionHandle>
        <aclh xsi:nil="true"/>
        <headId>0</headId>
        <headUserId>//--ID of event organizer-user--//</headUserId>
        <title>Event summary main text</title>
        <ident xsi:nil="true"/>
        <dimension1>0</dimension1>
        <dimension2>0</dimension2>
        <dimension3>0</dimension3>
        <taskTemplateId xsi:nil="true"/>
        <USER>
          <id>//--ID of event owner-user--//</id>
        </USER>
        <REPEAT>
          <repeatMode>2</repeatMode>
          <validFrom>2023-03-09T12:06:23</validFrom>
          <validTo>2023-04-09T00:00:00</validTo>
          <repeatEvery>1</repeatEvery>
          <repeatDay>0</repeatDay>
          <repeatMonth>0</repeatMonth>
          <repeatWeekDay>0</repeatWeekDay>
          <repeatWeekCount>0</repeatWeekCount>
          <repeatWeekDayList>4</repeatWeekDayList>
          <timeFrom>12:00</timeFrom>
          <timeTo>12:30</timeTo>
          <useOffset>0</useOffset>
          <offset>0</offset>
          <limit>1</limit>
        </REPEAT>
        <notify>1</notify>
        <refId></refId>
      </ITEM>
    </ns1:CreateEvent>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</persistency-request>

Example Response

Operation response: 'CreateEvent'
<persistency-response operationId='CreateEvent'>
<ns1:CreateEventResponse xmlns:ns1="http://atollon.com/enterprise/wsdl" xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/">
  <result>OK</result>
  <name>create</name>
  <headId>107751483081</headId>
  <commonId>107751484081</commonId>
  <newId>107751483081</newId>
</ns1:CreateEventResponse>
</persistency-response>

ContactFormRequest Service

Description

This service is used to simplify entering basic web forms into Atollon. In Atollon, it's possible to add more complex business logic based on request type and it's parameters. Web developers are let go of understanding Atollon blackbox.

Request

POST https://<HOST>/crab/contact_form/<request_type>?instance=<instance_name>

Request Types

Lead

https://<HOST>/crab/contact_form/lead?instance=<instance_name>

POST data in JSON format:

{
    "person": {
        "firstName": "<jmeno>",
        "lastName": "<prijmeni>"
    },
    "company": {
        "companyName": "<nazev_firmy>"
    },
    "contacts": {
        "email": "<email>",
        "phone": "<telefon>"
    },
    "comment": "<text_pozadavku>",
    "interestedIn": ["<p1>"," <p2>"," ..." ],
    "leadCategory": "<string>",
    "trackingCode": "<string>",
    "url": "<string>"
}

Function progress

Company lead
Person lead

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

 

 

Recruitment Functions

Recruitment Functions

Sending applicants to Atollon

The preffered way to send data into system is send them into CV inbox, which is done by the request described below. 

Sending candidate into CV inbox

New candidates (for example reactions from web advertisement) should be sent into atollon by channel for data import, based on object TemporaryImportFile (WS link). This is generic object, which can be used for needs of recruitment in the way, that you put candidate data into HR-XML standard (sample-CZ-HR-XML.json). The hr-xml allows us to understand candidate data, the other parameters of TemporaryImportFile gives us information about type of content, source (by source type or trackingCode) and so on.

RESTful API for candidate import

This is preffered way how to import candidates into atollon.

Please note that the following fields are entered in query as PARAMS. The "data" field contains JSON file in HR-XML format (as mentioned above). 

Field name Mandatory Meaning
apikey no Authentication token in case it is required
treehandle no Treenode
session no Session id -> else root seesion is used
user no Target user id (User can be usually found from tracking code)
team no Target team id (Team can eb usually found from tracking code in source)
reference no Contact ID, if the import file is referenced to existing contact.
data yes Candidate data in JSON based on HR-XML standard
source yes Text value of source. If not present, then will be replaced by data found based on tracking code. This information is only stored in the temporary import file and does not have any impact on other folders nor project in the system.
server yes Atollon application server
vacancyId no ID of vacancy(project)
vacancyRefId no reference ID of vacancy (If vacancyId not present it will be found from vacancyRefId. If also vacancyRefId is missing then vacancyId will be looked up with tracking code (if there is one))
letter no Text of motivational letter
custom3 no Field for custom client implementation
trackingCode no Tracking code, which represents a link to source medium (for example job advertisement gets its tracking code). When presented, tracking code is to get user and channel of original message action.

FILES

no attached CV, profile picture and so on. Instead of name of parametr "FILES" use name of the file, so it is properly treated.

attachments

no Attachments in json format {'attachment_id': 'attachment_filename'} - this is in case attachments are already in our filesystem and there is no need to import them again

Crawler Import Service

Description

This service is used to simplify importing data to ATOLLON. 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's blackbox.

Request

POST https://<HOST>/crab/crawler/<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/crawler/contact?instance=<instance_name>

Data in JSON format:

{
	"person": {
		"firstName": "<name>",
		"lastName": "<surname>",
        "prefixTitle": "<prefixTitle>",
        "postfixTitle": "<postfixTitle>",
		"companyPersonRelation": [{
			"companyExternalId": [{
				"system": "<system1>",
				"id": "<Company contact external ID>"
			}],
			"positionDesc": "<Position of person in company>",
			"companyName": "<Name of the related company>",
            "departmentName": "<Name of department>"
		}]
	},
	"company": {
		"companyName": "<company name>",
		"companyCompanyRelation": [{
			"companyExternalId": [{
				"system": "<system1>",
				"id": "<Company contact external ID>"
			}],
			"relationType": "<Relation type Mother company>"
		}]
	},
	"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": [{
		"name": "<Group 1>",
		"description": "<description>"
	}, {
		"name": "<Group 2>",
		"description": "<descritpion>"
	}],
	"contactFolder": [{
		"category": "<string1>",
		"refId": "",
		"parentFolder": {
			"category": "<string1>",
			"refId": "<string>",
			"contactExternalId": [{
				"system": "<system1>",
				"id": "<Company contact external ID>"
				}]
          	},
        "responsibleUser": [{
          "userName": "<user@workspace>",
          "userRoleName": "<User Role>",
          "primary": true
        	}]
      	}],
    "externalId": [{
        "system": "<system1>",
        "id": "<Contact old id>"
      }, {
        "system": "<system2>",
        "id": "<Contact old id>"
      }],
    "regNo": "<registered number of business>",
    "vatNo": "<VAT number>",
    "trackingCode": "<string>",
    "source": "<original - your system ident>",
    "industries": [{
        "name": "<industry name>",
        "description": "<industry description>"
    }]
}
Response

on SUCESS

Function progress

Company contact
Person contact

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
ExternalId

Please note that within Contact service, the system + externalId must be unique key.

Product

https://<HOST>/crab/crawler/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.0000,
    "unitPrice": 4990.00,
    "unitPriceCurrencyName": "<CZK, USD, etc.>",
    "statusName": "<Product status = Active, Inactive>",
    "unitsName": "<Product units = ks, md, hrs>",
    "vatRateName": "<15 %, 21%, etc.>",
    "openingBalanceQty": 0.0000,
    "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

Function progress

Billing

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

Request

GET https://<HOST>/crab/crawler/billing?billingStatus=ToBeInvoiced&instance=<instance_name>

Response
[{
	"activity": {
		"id": "0123000",
		"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": {
		"id": "<project id>",
		"name": "<Project name>",
		"refId": "<Project REF ID>",
		"statusName": "<Activity custom status name>",
		"description": "<Activity notes>",
		"created": "<2022-09-01T00:00>",
		"modified": "<2022-09-14T10:00>"
	},
	"folder": {
		"name": "<Folder name>",
		"refId": "<Folder REF ID>"
	},
	"contact": {
		"person": {
			"firstName": "<name>",
			"lastName": "<surname>"
		},
		"company": {
			"companyName": "<company name>"
		},
		"externalId": [{
			"system": "<system1>",
			"id": "<Contact old id>"
		}, {
			"system": "<sytem2>",
			"id": "<Contact old id>"
		}],
		"regNo": "<registered number of business>",
		"vatNo": "<VAT number>"
	},
    "customer": {
		"name": "<Folder name>",
		"refId": "<Folder REF ID>"
	},
	"customerContact": {
		"person": {
			"firstName": "<name>",
			"lastName": "<surname>"
		},
		"company": {
			"companyName": "<company name>"
		},
		"externalId": [{
			"system": "<system1>",
			"id": "<Contact old id>"
		}, {
			"system": "<sytem2>",
			"id": "<Contact old id>"
		}],
		"regNo": "<registered number of business>",
		"vatNo": "<VAT number>"
	},
	"billingItems": [{
        "id": "123456",
        "productName": "<Product name1>",
		"productRefid": "<Product code>",
		"name": "<Billing item text>",
		"description": "<Billing item description>",
		"quantity": 1.0000,
		"unitPrice": 1000.00,
		"currency": "<EUR, CZK, ...>",
		"billingDate": "<2022-09-14T10:00>",
        "billingStatus": "ToBeInvoiced",
		"productExternalId": [{
			"system": "<system1>",
			"id": "<Product old id>"
		}, {
			"system": "<sytem2>",
			"id": "<Product old id>"
		}]
	}, {
        "id": "123457",
		"productName": "<Product name2>",
		"productRefid": "<Product code>",
		"name": "<Billing item text>",
		"description": "<Billing item description>",
		"quantity": 1.0000,
		"unitPrice": 1000.00,
		"currency": "<EUR, CZK, ...>",
		"billingDate": "<2022-09-14T10:00>",
        "billingStatus": "ToBeInvoiced",
		"productExternalId": [{
			"system": "<system1>",
			"id": "<Product old id>"
		}, {
			"system": "<sytem2>",
			"id": "<Product old id>"
		}]
	}],
	"documents": [{
		"name": "<Document name>",
		"id": "123"
	}, {
		"name": "<Document name2>",
		"id": "456"

	}]
}]

Download documents

GET https://<HOST>/crab/crawler/download_document?docId=123123&instance=<instance_name>

You get file in response.

Update billing status of billing items

Run after you have processed the billing items from activity.

You can change status of each of the billing items. If billing items are marked as Invoiced, you can change either activity or project status. Activity status will be changed only if there are no remaining billing items to be invoiced.

Request

PUT https://<HOST>/crab/crawler/billing?instance=<instance_name>

DATA:

[{
  	"activity": {
		"id": "0123000",
		"statusName": "<Activity custom status name>"
	},
	"project": {
		"id": "<project id>",
		"statusName": "<Project custom status name>"
	},
	"billingItems": [{
		"id": "123456",
		"billingStatus": "Billed"
	}, {
		"id": "123457",
		"billingStatus": "Cancelled"
	}]
}]

Billing states:

0
SalesItems
1
Pending
2
ForApproval
3
ToBeInvoiced
4
Billed
5
ApprovedByClient
6
Postponed
7
Cancelled

Project

Request

Create new project and add technology items:

POST https://<HOST>/crab/crawler/project?instance=<instance_name>

{
	"project": {
		"id": "<project id>",
		"name": "<Project name>",
		"refId": "<Project REF ID>",
		"statusName": "<Activity custom status name>",
		"description": "<Activity notes>",
		"created": "<2022-09-01T00:00>",
		"modified": "<2022-09-14T10:00>",
		"category": "anyProjectCategory",
    	"externalId": [{
        	"system": "<system1>",
        	"id": "<Contact old id>"
      	}, {
        	"system": "<system2>",
        	"id": "<Contact old id>"
      	}],
        "dimension1Name": "<dimension1Name>",
        "dimension2Name": "<dimension2Name>",
        "dimension3Name": "<dimension3Name>",
        "customer": {
            "contactExternalId": [{
                "system": "<system1>",
                "id": "<customer contact externalid>"
                }],
            "contextCategory": "anyFolderCategory"
            }
	},
	"folder": {
		"name": "<Folder name>",
		"refId": "<Folder REF ID>",
        "category": "anyFolderCategory"

	},
	"contact": {
		"person": {
			"firstName": "<name>",
			"lastName": "<surname>"
		},
		"company": {
			"companyName": "<company name>"
		},
		"externalId": [{
			"system": "<system1>",
			"id": "<Contact old id>"
		}, {
			"system": "<sytem2>",
			"id": "<Contact old id>"
		}],
		"regNo": "<registered number of business>",
		"vatNo": "<VAT number>"
	},
	"technologyItems": [{
        "id": "123456",
        "productName": "<Product name1>",
		"productRefid": "<Product code>",
		"name": "<Technology item text>",
		"description": "<Technology item description>",
		"quantity": 1.0000,
		"unitPrice": 1000.00,
		"currency": "<EUR, CZK, ...>",
		"billingDate": "<2022-09-14T10:00>",
        "refId":"<Serial number>",
		"externalId": [{
			"system": "<system1>",
			"id": "<Product old id>"
		}, {
			"system": "<sytem2>",
			"id": "<Product old id>"
		}],
        "supplier": {
            "contactExternalId": [{
                "system": "test",
                "id": "123"
                }]
            }
	}, {
        "id": "123457",
		"productName": "<Product name2>",
		"productRefid": "<Product code>",
		"name": "<Technology item text>",
		"description": "<Technology item description>",
		"quantity": 1.0000,
		"unitPrice": 1000.00,
		"currency": "<EUR, CZK, ...>",
		"billingDate": "<2022-09-14T10:00>",
        "refId":"<Serial number>",
		"externalId": [{
			"system": "<system1>",
			"id": "<Product old id>"
		}, {
			"system": "<sytem2>",
			"id": "<Product old id>"
		}]
	}],
    "formValues": [{
        "fieldIdent": "<textFormItem>",
        "fieldValue": "<hello>"
        }, {
        "fieldIdent": "<numberFormItem>",
        "fieldValue": 22
        }, {
        "fieldIdent": "<dateFormItem>",
        "fieldValue": "<2023-05-23T00:00:00>"
        }]
}

Internal Procedure

Request

Update project status:

PUT https://<HOST>/crab/crawler/project?instance=<instance_name>

{
	"project": {
		"id": "<project id>",
		"name": "<Project name>",
		"refId": "<Project REF ID>",
		"statusName": "<Activity custom status name>",
		"description": "<Activity notes>",
		"created": "<2022-09-01T00:00>",
		"modified": "<2022-09-14T10:00>",
		"category": "anyProjectCategory",
		"externalId": [{
			"system": "<system1>",
			"id": "<Contact old id>"
		}, {
			"system": "<system2>",
			"id": "<Contact old id>"
		}],
        "dimension1Name": "<dimension1Name>",
        "dimension2Name": "<dimension2Name>",
        "dimension3Name": "<dimension3Name>",
        "customer": {
            "contactExternalId": [{
                "system": "<system1>",
                "id": "<customer contact externalid>"
                }],
            "contextCategory": "anyFolderCategory"
      		}
	},
    "technologyItems": [],
    "formValues": []
}

Activity

GetActivity

Request

GET https://<HOST>/crab/crawler/activity?instance=<instance_name>&id=<activity_id>

Optional url param billingStatus for activity including billing items

Response
{
    "acl": "TREE000000228302",
    "aclh": "TREE000000228302",
    "activityType": 449312101,
    "activityTypeName": "Pravideln\\u00fd servis",
    "created": "2023-08-01T16:53:14.198186",
    "createdByName": "admin@pioneer",
    "customState": 132412101,
    "defaultMessageContainer": 773533101,
    "defaultMessageContainerPath": "ABC DESIGN Branch > Servisn\\u00ed projekt > Activity > Pravideln\\u00fd servis",
    "defaultMessageGroup": 773226101,
    "folder": 773157101,
    "folderName": "ABC DESIGN Branch",
    "folderTypeName": "Company Branch",
    "customer": {
        "contactExternalId": [
            {
                "system": "<system1>",
                "id": "<customer contact externalid>"
            }
        ]
    },
    "supplier": {
        "contactExternalId": [
            {
                "system": "<system1>",
                "id": "<customer contact externalid>"
            }
        ]
    },
    "formId": 449320101,
    "formName": "Service Activity",
    "formValues": 773535101,
    "id": 773533101,
    "modified": "2023-08-01T17:30:14.828457",
    "modifiedByName": "admin@pioneer",
    "name": "Pravideln\\u00fd servis",
    "project": 773225101,
    "projectName": "Servisn\\u00ed projekt",
    'projectExternalId': [
            {
                "system": "<system1>",
                "id": "<project externalid>"
            }
        ],
    "refId": "0348",
    "state": 1,
    "requestHash": "NULL",
    "startDate": "2024-09-01T00:00:00.000000",
    "finalDate": "2026-01-31T00:00:00.000000",
    "dimension1Name": "China",
    "dimension2Name": "Mobile",
    "dimension3Name": "Internal",
    "EXTERNAL_CONTACTS": {
        "count": 0,
        "EXTERNAL_CONTACT": []
    }
	"documents": [{
		"name": "<Document name>",
		"id": "123"
	}, {
		"name": "<Document name2>",
		"id": "456"

	}]
}

ListActivity

Request

GET https://<HOST>/crab/crawler/activity?instance=<instance_name>&category=<fpatypecategory>&createdFrom=<created_from>&statusName="Initial"&dimension1Name="Organization Unit A"

Response
[
    {
        "id": 773460101,
        "name": "Pravideln\u00fd servis",
        "type": 449312101,
        "typeName": "Pravideln\u00fd servis",
        "state": 3,
        "customState": 132416101,
        "customStateName": "Closed",
        "created": "2023-08-01T15:55:56.385675",
        "createdBy": 131750101,
        "createdByName": "admin@pioneer",
        "modified": "2023-08-01T16:53:11.718562",
        "modifiedBy": 131750101,
        "modifiedByName": "admin@pioneer",
        "organization": 130946101,
        "folder": 773157101,
        "folderName": "ABC DESIGN Branch",
        "folderParentId": 700827101,
        "folderParentName": "ABC DESIGN",
        "project": 773225101,
        "projectName": "Servisn\u00ed projekt",
        "refId": "0347",
        "requestHash": "NULL",
        "defaultMessageContainer": 773460101,
        "defaultMessageGroup": 773226101,
        "formId": 449320101,
        "formValues": 773462101,
        "startDate": "2023-04-01T00:00:00.000000",
        "finalDate": "2024-08-31T00:00:00.000000",
        "dimension1Name":"China",
        "dimension2Name":"Mobile",
        "dimension3Name":"Internal",
    },
    {
        "id": 773533101,
        "name": "Pravideln\u00fd servis",
        "type": 449312101,
        "typeName": "Pravideln\u00fd servis",
        "state": 1,
        "customState": 132412101,
        "customStateName": "Initial",
        "created": "2023-08-01T16:53:14.198186",
        "createdBy": 131750101,
        "createdByName": "admin@pioneer",
        "modified": "2023-08-01T17:30:14.828457",
        "modifiedBy": 131750101,
        "modifiedByName": "admin@pioneer",
        "organization": 130946101,
        "folder": 773157101,
        "folderName": "ABC DESIGN Branch",
        "folderParentId": 700827101,
        "folderParentName": "ABC DESIGN",
        "project": 773225101,
        "projectName": "Servisn\u00ed projekt",
        "refId": "0348",
        "requestHash": "NULL",
        "defaultMessageContainer": 773533101,
        "defaultMessageGroup": 773226101,
        "formId": 449320101,
        "formValues": 773535101,
        "startDate": "2024-09-01T00:00:00.000000",
        "finalDate": "2026-01-31T00:00:00.000000",
        "dimension1Name":"China",
        "dimension2Name":"Mobile",
        "dimension3Name":"Internal",
    }
]

UpdateActivity

Request

PUT https://<HOST>/crab/crawler/activity?instance=<instance_name>

{
    "activity": {
        "id": "<activity_id>",
        "name": "Pravideln\u00fd servis",
        "refId": "0348",
        "statusName": "In Progress",
        "requestHash": "NULL",
        "startDate": "2024-09-01T00:00:00.000000",
        "finalDate": "2026-01-31T00:00:00.000000",
        "EXTERNAL_CONTACTS": {
            "count": 0,
            "EXTERNAL_CONTACT": []
        }
    },
	"billingItems": [{
        "id": "123456",
        "productName": "<Product name1>",
		"productRefid": "<Product code>",
		"name": "<Billing item text>",
        "refId": "<Billing item refid text>",
		"description": "<Billing item description>",
		"quantity": 1.0000,
		"unitPrice": 1000.00,
        "vatValue": 21.0,
		"currency": "<EUR, CZK, ...>",
		"billingDate": "<2022-09-14T10:00>",
        "billingStatus": "ToBeInvoiced",
		"productExternalId": [{
			"system": "<system1>",
			"id": "<Product old id>"
		}, {
			"system": "<sytem2>",
			"id": "<Product old id>"
		}]
	}, {
        "id": "123457",
		"productName": "<Product name2>",
		"productRefid": "<Product code>",
		"name": "<Billing item text>",
        "refId": "<Billing item refid text>",
		"description": "<Billing item description>",
		"quantity": 1.0000,
		"unitPrice": 1000.00,
        "vatValue": 21.0,
		"currency": "<EUR, CZK, ...>",
		"billingDate": "<2022-09-14T10:00>",
        "billingStatus": "ToBeInvoiced",
		"productExternalId": [{
			"system": "<system1>",
			"id": "<Product old id>"
		}, {
			"system": "<sytem2>",
			"id": "<Product old id>"
		}]
	}]
}

Tracking code

Request

POST https://<HOST>/crab/crawler/tracking_code?instance=<instance_name>

{
	"code": "ABC",
	"userName": "<-- username@workspace -->",
	"trackingCodeTypeName": "<-- Dealer -->",
	"contactFolder": {
      	"id": "<Folder id>",
		"name": "<Folder name>",
		"refId": "<Folder REF ID>",
		"category": "anyFolderCategory",
		"contact": {
			"person": {
				"firstName": "<name>",
				"lastName": "<surname>"
			},
			"company": {
				"companyName": "<company name>"
			},
			"externalId": [{
				"system": "<system1>",
				"id": "<Contact old id>"
			}, {
				"system": "<sytem2>",
				"id": "<Contact old id>"
			}]
		}
	}
}
Internal process

The service calls service for creating tracking code.

The aim is to file new trackingCode with type "Dealer" or "Partner" with rerefence to folderId having contact's externalId previously entered by contact service.