gold-link api documentation
TRANSCRIPT
Gold-Link API DocumentationRelease 0.0.6
Gold-Vision
Sep 06, 2017
Contents
1 Getting Started 31.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Connecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 HTTP SOAP Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 SOAP Request Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.5 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Methods 72.1 Basic Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Finding, Listing, Get Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3 Add/Update/Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.4 Phone System Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3 Gold-Vision Items 213.1 Gold-Vision Model Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.2 Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233.3 Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273.4 Opportunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273.5 Events/Seminars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.6 Phone Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4 Code Samples 354.1 Javascript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354.2 PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374.3 C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
i
ii
Gold-Link API Documentation, Release 0.0.6
Contents 1
Gold-Link API Documentation, Release 0.0.6
2 Contents
CHAPTER 1
Getting Started
Introduction
The Gold-Link API is a SOAP based Web Service that is installed as part of the core product. The API is used bysending XML requests over the HTTP protocol.
In order to use the API you must be using a logical programming language that supports SOAP Web Service interop-erability. The recommended choice on a Windows platform is to use .NET Framework and on a Linux platform is touse PHP.
Note: If using .NET Framework, the Gold-Vision API web service can be automatically integrated using the VisualStudio “Add Web Reference” option. More information on how to use this feature can be found here - .
Connecting
The API needs to be enabled through the product licence. If the API is not enabled for your installation or instance,please contact Gold-Vision Support at [email protected] or +44(0) 1788 511 110 (UK & Europe) or +1 (647)494 9870 (North America) | +1 (877)673 1230 (Toll-Free)
Address
You can access the web service by using the URL:
<your Gold-Vision URL>/gold-link/goldlink.asmx
For example:
https://example.goldvisioncrm.com/gold-link/goldlink.asmx
3
Gold-Link API Documentation, Release 0.0.6
Note:
• The Gold-Vision API is built into individual implementations and therefore the URL will be unique for a par-ticular install.
• Visiting the web service URL will let you view a list of the available methods through the API.
Authentication
Authentication is performed using NTLM Authentication. Therefore, to use the API, the user’s credentials must matchthat of a valid Gold-Vision user.
HTTP SOAP Example
The following is a sample SOAP request and response for the method AddItem.
Request
POST /example.goldvisioncrm.com/gold-link/goldlink.asmx HTTP/1.1Host: example.goldvisioncrm.comContent-Type: application/soap+xml; charset=utf-8
<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd=
→˓"http://www.w3.org/2001/XMLSchema" xmlns:soap="http://service.gold-vision.com/gold-→˓link">
<soap:Body><AddItem xmlns="http://service.gold-vision.com/gold-link"><objectType>Account</objectType><xmlData><gvdata xmlns=""><record><field name="SUMMARY">Holding Ltd</field><field name="NAME">Holding Ltd</field><field name="ADDRESS_1">321 New Street</field><field name="TOWN">London</field><field name="COUNTRY">United Kingdom</field>
</record></gvdata></xmlData>
</AddItem></soap:Body>
</soap:Envelope>
Response
HTTP/1.1 200 OKContent-Type: application/soap+xml; charset=utf-8Content-Length: length
<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd=
→˓"http://www.w3.org/2001/XMLSchema" xmlns:soap="http://service.gold-vision.com/gold-→˓link">
4 Chapter 1. Getting Started
Gold-Link API Documentation, Release 0.0.6
<soap:Body><AddItemResponse xmlns="http://service.gold-vision.com/gold-link">
<AddItemResult>true</AddItemResult><returnId>71fb89cb-92ad-4973-8293-d43f1cd98673</returnId><success>true</success><message></message>
</AddItemResponse></soap:Body>
</soap:Envelope>
SOAP Request Testing
If you are unfamiliar with making SOAP requests, a good point to start with is to use a Functional Testing solutionsuch as .
By using a solution such as SoapUI, you are able to send requests to Gold-Link and observe the responses within auser friendly user interface.
Note: Throughout the rest of this documentation, all of the SOAP requests and responses have been generated usinga Functional Testing solution.
Handling Errors
Part of the XML response for any API call is success and message. If the API call failed for any reason, success willbe false and message will contain the error message.
The Gold-Vision log files will contain detailed error messages and can be accessed through Settings > Logging withinthe Administration Console. The file containing the Gold-Link errors will be labelled as Gold-Link_{date}.txt.
1.4. SOAP Request Testing 5
Gold-Link API Documentation, Release 0.0.6
6 Chapter 1. Getting Started
CHAPTER 2
Methods
Note: A full list of available methods can be found by accessing the web service URL e.g. https://example.goldvisioncrm.com/gold-link/goldlink.asmx.
Basic Methods
GetVersion
This method is used to get the version number of your Gold-Vision instance.
Request
Attribute TypeEmpty N/A
Response
Attribute TypeGetVersionResult String
No parameters are required to make a GetVersion request. For example, the following request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:GetVersion/></soapenv:Body>
</soapenv:Envelope>
will return with the following response:
7
Gold-Link API Documentation, Release 0.0.6
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><GetVersionResponse xmlns="http://service.gold-vision.com/gold-link">
<GetVersionResult>7.0.18.17056</GetVersionResult></GetVersionResponse>
</soap:Body></soap:Envelope>
The <GetVersionResult> node has returned the Gold-Vision version number.
Finding, Listing, Get Items
FindItem (List Items)
This method is used to return a list of records from Gold-Vision that match the objectType, filter, field, rowlimit andsort nodes provided.
Request
Attribute (Required/Optional) TypeobjectType ObjectTypefilters <filters>
<filter dbcolumn=”” value=””type=”“></filter><rowlimit value=”“></rowlimit><sort dbcolumn=”” order=”“></sort>
</filters>
Response
Attribute TypeFindItemResult Listsuccess Booleanmessage String
For a FindItem request, you will be required to send an objectType and filters node. The following nodes canbe applied within filters to narrow down your FindItem result list.
filter
The filter node is can be used to search for a specific field value. For example the following request will search for allAccounts that have a SUMMARY of ‘Gold-Vision’.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:FindItem><gold:objectType>Account</gold:objectType><gold:XmlFilters>
<filters xmlns=""><filter dbcolumn="SUMMARY" value="Gold-Vision" /></→˓filters>
</gold:XmlFilters></gold:FindItem>
8 Chapter 2. Methods
Gold-Link API Documentation, Release 0.0.6
</soapenv:Body></soapenv:Envelope>
sort
The sort node is used to apply a sorting criteria to the result set. For example, the following request will return allAccounts but in a descending order with regards to their SUMMARY value.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:FindItem><gold:objectType>Account</gold:objectType><gold:XmlFilters>
<filters xmlns=""><sort dbcolumn="SUMMARY" order="desc" /></sort></gold:XmlFilters>
</gold:FindItem></soapenv:Body>
</soapenv:Envelope>
rowlimit
The rowlimit node is used to limit the amount of records returned in the response. For example, the following requestwill return only 2 Accounts from all the Accounts in Gold-Vision.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:FindItem><gold:objectType>Account</gold:objectType><gold:XmlFilters>
<filters xmlns=""><rowlimit value="2" /></rowlimit></gold:XmlFilters>
</gold:FindItem></soapenv:Body>
</soapenv:Envelope>
The following request uses all 3 filtering nodes to return 2 Accounts that begin with the letter ‘G’ and have been sortedin an alphabetically order.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:FindItem><gold:objectType>Account</gold:objectType><gold:XmlFilters>
<filters xmlns=""><filter dbcolumn="SUMMARY" value="G"></filter><sort dbcolumn="SUMMARY" order="asc"></sort><rowlimit value="3"></rowlimit>
</filters></gold:XmlFilters>
</gold:FindItem></soapenv:Body>
</soapenv:Envelope>
2.2. Finding, Listing, Get Items 9
Gold-Link API Documentation, Release 0.0.6
Here is the response:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><FindItemResponse xmlns="http://service.gold-vision.com/gold-link">
<FindItemResult><gvdata xmlns="">
<list records="2"><record id="4f219888-55c6-405a-95be-60281c14778e
→˓" type="Account" ac_id="4f219888-55c6-405a-95be-60281c14778e" summary="General Sales→˓"/>
<record id="b1c966b1-cc83-4594-a68c-c4e6522a5107→˓" type="Account" ac_id="b1c966b1-cc83-4594-a68c-c4e6522a5107" summary="Gold-Vision"/→˓>
</list></gvdata>
</FindItemResult><success>true</success><message/>
</FindItemResponse></soap:Body>
</soap:Envelope>
GetItem
This method is used to get all of the information for a particular record.
Request
Attribute (Required/Optional) TypeobjectType ObjectTypeid StringreturnEmptyFields Boolean
Response
Attribute TypeGetItemResult Xmlsuccess Booleanmessage String
To make a request using GetItem, you will be required to make a request with an objectType, id andreturnEmptyFields node. The returnEmptyFields node will accept a value of either true (1) or false(0).
The following request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:GetItem><gold:objectType>Account</gold:objectType><gold:id>b1c966b1-cc83-4594-a68c-c4e6522a5107</gold:id><gold:returnEmptyFields>false</gold:returnEmptyFields>
</gold:GetItem>
10 Chapter 2. Methods
Gold-Link API Documentation, Release 0.0.6
</soapenv:Body></soapenv:Envelope>
will return a response of:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><GetItemResponse xmlns="http://service.gold-vision.com/gold-link">
<GetItemResult><gvdata xmlns="">
<record objecttype="Account" id="b1c966b1-cc83-4594-→˓a68c-c4e6522a5107">
<field name="AC_ID" readOnly="true">b1c966b1-→˓cc83-4594-a68c-c4e6522a5107</field>
<field name="SUMMARY" label="Account Name"→˓details="">Gold-Vision</field>
<field name="ACG_ID" type="uid" label="Security→˓" details="" id="78b6dbd2-8611-4e6d-9360-ddc40fe61066">Public</field>
<field name="AC_NUMBER" label="Account Number">→˓</field>
<field name="AC_POTENTIAL" readOnly="true"→˓label="Account Potential" type="numeric">70,425.00</field>
<field name="AC_SALES" readOnly="true" label=→˓"Account Sales" type="numeric">0.00</field>
<field name="AC_DISCOUNT" type="number" label=→˓"Discount">0.0E0</field>
<field name="NAME" label="Account Name">Gold-→˓Vision</field>
...
...</record>
</gvdata></GetItemResult><success>true</success><message/>
</GetItemResponse></soap:Body>
</soap:Envelope>
Add/Update/Delete
AddItem
This method is used to add a new record into Gold-Vision.
Request
Attribute (Required/Optional) TypeobjectType ObjectTypexmlData Xml
Response
2.3. Add/Update/Delete 11
Gold-Link API Documentation, Release 0.0.6
Attribute TypeAddItemResult BooleanreturnId Stringsuccess Booleanmessage String
To add a new item in Gold-Vision, you are required to make a request with an objectType and xmlData node.The xmlData node is to contain data for each field related to your new item that you are adding.
This request will add a new Account into Gold-Vision with a SUMMARY value of ‘Esteiro’:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:AddItem><gold:objectType>Account</gold:objectType><gold:xmlData><gvdata xmlns="">
<record><field name="SUMMARY">Esteiro</field></record></gvdata></gold:xmlData>
</gold:AddItem></soapenv:Body>
</soapenv:Envelope>
This request will return a response of:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><AddItemResponse xmlns="http://service.gold-vision.com/gold-link">
<AddItemResult>true</AddItemResult><returnId>09b54b7a-2de1-46da-8b0f-b42debe9f2ba</returnId><success>true</success><message/>
</AddItemResponse></soap:Body>
</soap:Envelope>
If successful, the response will return the new item ID under returnId. The above example will have created anew Account with just a SUMMARY value and nothing else. To create a new Account with more data, you will berequired to nest the relevant field nodes within the record node.
UpdateItem
This method is used to update an existing record in Gold-Vision.
Request
Attribute(Required/Optional)
Type
objectType ObjectTypexmlData Xmlid Stringoverwrite AllFieldsPresent or AllFieldsPresentExceptBlanks or
AllFieldsPresentExceptBlanksWhereTargetEmpty
12 Chapter 2. Methods
Gold-Link API Documentation, Release 0.0.6
Response
Attribute TypeUpdateItemResult Booleansuccess Booleanmessage String
To make a request using UpdateItem, you will be required to make a request with an objectType, xmlData, idand overwrite node. The overwrite node can either have a value of AllFieldsPresent, AllFieldsPresentEx-ceptBlanks or AllFieldsPresentExceptBlanksWhereTargetEmpty.
The following request is to update the SUMMARY field to have a value of ‘Esteiro’ for an Account with the given ID.The following value given for the overwrite node will overwrite the existing data even if it is blank.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:gold="http:/→˓/service.gold-vision.com/gold-link">
<soap:Header/><soap:Body>
<gold:UpdateItem><gold:objectType>Account</gold:objectType><gold:xmlData><gvdata xmlns="">
<record><field name="SUMMARY">Esteiro</field></record></gvdata></gold:xmlData><gold:id>b1c966b1-cc83-4594-a68c-c4e6522a5107</gold:id><gold:overwrite>AllFieldsPresent</gold:overwrite>
</gold:UpdateItem></soap:Body>
</soap:Envelope>
This request will return with a response of:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://→˓www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body><UpdateItemResponse xmlns="http://service.gold-vision.com/gold-link">
<UpdateItemResult>true</UpdateItemResult><success>true</success><message/>
</UpdateItemResponse></soap:Body>
</soap:Envelope>
This response has indicated that the update has been successful.
GetObjectDef
This method is useful when you want to get a list of possible fields available, when looking to create a new record inGold-Vision.
Request
Attribute (Required/Optional) TypeobjectType ObjectType
Response
2.3. Add/Update/Delete 13
Gold-Link API Documentation, Release 0.0.6
Attribute TypeGetObjectDefResult Xmlsuccess Booleanmessage String
The GetObjectDef request only requires you to include the objectType node with the request. From this, a responsewill be returned that includes ObjectDef information related to the value included in objectType such as field namesand field labels.
This request will return the ObjectDef information of an Account item:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:GetObjectDef><gold:objectType>Account</gold:objectType>
</gold:GetObjectDef></soapenv:Body>
</soapenv:Envelope>
Here is a preview of the response that will be returned:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><GetObjectDefResponse xmlns="http://service.gold-vision.com/gold-link">
<GetObjectDefResult><record compatibility="6" queryCommand="spGetAccount"
→˓updateCommand="spUpdateAccount" insertCommand="spInsertAccount" deleteCommand=→˓"spDeleteAccount" undeleteCommand="spUnDeleteAccount" dormantCommand=→˓"spDormantAccount" unDormantCommand="spUnDormantAccount" openby="" opendate="" id="→˓" xmlns="">
<field name="AC_ID" primarykey="true" readOnly="true"→˓location="" colspan=""/>
<field name="SUMMARY" ui="true" label="Account Name"→˓labelref="[%ACCOUNTS] Name" templatetag="account" integtype="text" icon="template"→˓details="" editincludesecondaryteam="false" geocode="false" location="s1r1c1"→˓colspan="2"/>
<field name="ACG_ID" ui="true" type="uid" dropdown=→˓"spGetDrop AC_ACCESS" label="Security" labelref="Security" details=""→˓editincludesecondaryteam="false" geocode="false" location="s2r9c3" colspan="2"/>
<field name="AC_NUMBER" label="Account Number"→˓labelref="[%ACCOUNTS] Number" location="" colspan=""/>
<field name="AC_POTENTIAL" readOnly="true" ui="true"→˓label="Account Potential" labelref="[%ACCOUNTS] Potential" type="numeric" integtype=→˓"numeric" location="" colspan=""/>
<field name="AC_SALES" readOnly="true" ui="true" label=→˓"Account Sales" labelref="[%ACCOUNTS] Sales" type="numeric" integtype="numeric"→˓location="" colspan=""/>
<field name="AC_DISCOUNT" templatetag="ac_discount" ui=→˓"true" dropdown="spGetDropDiscount" type="number" label="Discount" integtype=→˓"numeric" location="" colspan=""/>
<field name="NAME" label="Account Name" labelref="[→˓%ACCOUNTS] Name" templatetag="account" integtype="text" location="" colspan=""/>
<field name="AC_FLAG" templatetag="ac_flag" ui="true"→˓type="uid" dropdown="spGetDrop AC_FLAG" label="Support Status" integtype="text"→˓details="" editincludesecondaryteam="false" geocode="false" mustHaveInsert="false"→˓mustHaveUpdate="false" editableUI="0" dro="AC_FLAG" location="s1r4c3" colspan="2"/>
14 Chapter 2. Methods
Gold-Link API Documentation, Release 0.0.6
<field name="US_ID_SALES" templatetag="ac_manager" ui=→˓"true" type="uid" dropdown="spDropDownSalesUsers 'SALES'" label="Account Manager"→˓labelref="[%ACCOUNTS] Manager" owner="true" integtype="text" icon="email:OWNER_EMAIL→˓" link="OpenUser:US_ID_SALES" details="" editincludesecondaryteam="false" geocode=→˓"false" location="s1r4c1" colspan="2"/>
...</record>
</GetObjectDefResult><success>true</success><message/>
</GetObjectDefResponse></soap:Body>
</soap:Envelope>
Just like FindItem (List Items), a success node is returned along with the record node to indicate if the request issuccessful or not.
GetDropOptions
This method is useful when getting a list of the available dropdown values for a dropdown field.
Attribute (Required/Optional) TypeobjectType ObjectTypefieldName String
Response
Attribute TypeGetDropOptionsResult Listsuccess Booleanmessage String
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:GetDropOptions><gold:objectType>Account</gold:objectType><gold:fieldName>AC_FLAG</gold:fieldName>
</gold:GetDropOptions></soapenv:Body>
</soapenv:Envelope>
This request will return the following response that contains all the available values for the field AC_FLAG which islabelled as Support Status by default.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><GetDropOptionsResponse xmlns="http://service.gold-vision.com/gold-link
→˓"><GetDropOptionsResult>
<drop xmlns=""><row value="" text="Not Set" hlight=""/><row value="cf834a75-3223-45ef-b555-50331109a950" text=
→˓"ACTIVE SUPPORT" hlight=""/>
2.3. Add/Update/Delete 15
Gold-Link API Documentation, Release 0.0.6
<row value="c2c40237-f662-4f3d-913f-81e482fa4ca6" text=→˓"NEW CUSTOMER" hlight=""/>
<row value="cf1fea76-00a2-4e54-b5ac-eaf80e6d3f64" text=→˓"RESELLER - 2ND LINE SUPPORT" hlight=""/>
<row value="dbd76c91-baed-4011-b449-0fb2dbc0135a" text=→˓"HOLD" hlight=""/>
<row value="ac425e3c-7d3d-4c69-8256-eef47e9cf60c" text=→˓"UNSUPPORTED" hlight=""/>
</drop></GetDropOptionsResult><success>true</success><message/>
</GetDropOptionsResponse></soap:Body>
</soap:Envelope>
If making an Add/Update/Delete request to set a dropdown field such as AC_FLAG/Support Status, you would haveto use the relevant GUID ID from the dataset returned from the GetDropOptions request.
DeleteItem
This method is used to delete records in Gold-Vision.
Attribute (Required/Optional) TypeobjectType ObjectTypeid String
Response
Attribute TypeDeleteItemResult Booleansuccess Booleanmessage String
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:DeleteItem><gold:objectType>Contact</gold:objectType><gold:id>b3cc266e-4e98-4f6e-aee3-5b6915ee62a3</gold:id>
</gold:DeleteItem></soapenv:Body>
</soapenv:Envelope>
Phone System Methods
LogCall
This method is used to log incoming and outgoing telephone calls within Gold-Vision.
16 Chapter 2. Methods
Gold-Link API Documentation, Release 0.0.6
Attribute (Required/Optional) TypeaccountId StringcontactId Stringnumber Stringinbound Boolean
Response
Attribute TypeLogCallResult Booleansuccess Booleanmessage String
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:LogCall><gold:accountId>71fb89cb-92ad-4973-8293-d43f1cd98673</
→˓gold:accountId><gold:contactId>ca194711-f378-48c4-88f2-b8ae22207091</
→˓gold:contactId><gold:number>01234 567890</gold:number><gold:inbound>true</gold:inbound>
</gold:LogCall></soapenv:Body>
</soapenv:Envelope>
This request will return a result with a success node and a message node. If success appears as ‘false’, themessage node will display the error that caused the request to fail.
Note: It is possible to send this request without a contactId value. By leaving this node empty, a telephone callwill be entered into Gold-Vision against the given Account rather than against a Contact.
LogCallwithDuration
This method is used to log incoming and outgoing telephone calls with a duration value in Gold-Vision.
Attribute (Required/Optional) TypeaccountId StringcontactId Stringnumber Stringinbound Booleanduration Integer
Response
Attribute TypeLogCallwithDurationResult Booleansuccess Booleanmessage String
This is what a LogCallWithDuration request will look like:
2.4. Phone System Methods 17
Gold-Link API Documentation, Release 0.0.6
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:LogCallwithDuration><gold:accountId>71fb89cb-92ad-4973-8293-d43f1cd98673</
→˓gold:accountId><gold:contactId>ca194711-f378-48c4-88f2-b8ae22207091</
→˓gold:contactId><gold:number>01234 567890</gold:number><gold:inbound>true</gold:inbound><gold:duration>3</gold:duration>
</gold:LogCallwithDuration></soapenv:Body>
</soapenv:Envelope>
This request adds an inbound telephone call against the Contact Joe Bloggs and Account Holding Ltd as well asgiving the record a duration value of 3.
LookupPhoneNumber
This method is useful when looking to return all matching Contacts and Accounts with the input of a telephone number.
Attribute (Required/Optional) Typenumber String
Response
Attribute TypeLookupPhoneNumberResult Booleansuccess Booleanmessage String
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:LookupPhoneNumber><gold:number>01234 567890</gold:number>
</gold:LookupPhoneNumber></soapenv:Body>
</soapenv:Envelope>
The response will return a list node that will contain both account and contact records if any match thetelephone number sent with the original request. This is the sort of response that you are likely to receive:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><LookupPhoneNumberResponse xmlns="http://service.gold-vision.com/gold-
→˓link"><LookupPhoneNumberResult>
<gvdata xmlns=""><list>
<account id="71fb89cb-92ad-4973-8293-→˓d43f1cd98673">
18 Chapter 2. Methods
Gold-Link API Documentation, Release 0.0.6
<ac_name>Holding Ltd</ac_name><ac_id>71fb89cb-92ad-4973-8293-
→˓d43f1cd98673</ac_id><ac_phone/><ac_link>http://gvsandbox01/Gold-
→˓VisionThorne/goldvision.aspx?page=popthru&killwindow=1&action=OpenAccount&→˓amp;actiondata=71fb89cb-92ad-4973-8293-d43f1cd98673</ac_link>
<contacts><contact id="ca194711-f378-48c4-
→˓88f2-b8ae22207091"><acc_name>Joe Bloggs</acc_name><acc_id>ca194711-f378-48c4-
→˓88f2-b8ae22207091</acc_id><acc_phone>01234 567890</acc_
→˓phone><acc_mobile/><acc_link>http://gvsandbox01/
→˓Gold-VisionThorne/goldvision.aspx?page=popthru&killwindow=1&→˓action=OpenContact&actiondata=ca194711-f378-48c4-88f2-b8ae22207091</acc_link>
<acc_match>true</acc_match></contact>
</contacts></account>
</list></gvdata>
</LookupPhoneNumberResult><success>true</success><message/>
</LookupPhoneNumberResponse></soap:Body>
</soap:Envelope>
2.4. Phone System Methods 19
Gold-Link API Documentation, Release 0.0.6
20 Chapter 2. Methods
CHAPTER 3
Gold-Vision Items
Gold-Vision Model Diagram
The diagram below helps you to gain a basic understanding of the structure for Gold-Vision items. So for example,to create a new Contact in Gold-Vision, it can be seen that it is dependent on the Account item. Therefore, creating anew Contact will require you to pass an AC_ID of an existing Account in the request.
21
Gold-Link API Documentation, Release 0.0.6
Core Items
Seminars
Things can become a little more difficult if creating a new Seminar Session Attendee record compared to a simple
22 Chapter 3. Gold-Vision Items
Gold-Link API Documentation, Release 0.0.6
Contact record. By looking at the above diagram, creating a new Seminar Session Attendee record in Gold-Visionrequires you to have a Seminar Session and a Seminar Booking Attendee. However, the Seminar Session requires aSeminar. Also, the Seminar Booking Attendee is dependent on a Seminar Booking of which is dependent on a Seminarand an Account.
Therefore, creating a Seminar Session Attendee record requires you to have a Seminar Session, Seminar BookingAttendee, Seminar Booking, Seminar and Account. In contrast, creating a Contact only requires an Account.
Warning: Using AddItem with an objectType value of Campaign will add a Campaign in Legacy Campaignmode and not in New Campaign mode.
Account
For this example, an Account called Holdings Ltd will be added into Gold-Vision.
Finding an Existing Account
First make a Gold-Link request using FindItem (List Items) to find any Accounts that already have the name HoldingsLtd.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:FindItem><gold:objectType>Account</gold:objectType><gold:XmlFilters>
<filters xmlns=""><filter dbcolumn="SUMMARY" value="Holdings Ltd" />
</filters></gold:XmlFilters>
</gold:FindItem></soapenv:Body>
</soapenv:Envelope>
This is the response:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><FindItemResponse xmlns="http://service.gold-vision.com/gold-link">
<FindItemResult><gvdata xmlns="">
<list records="0"/></gvdata>
</FindItemResult><success>true</success><message/>
</FindItemResponse></soap:Body>
</soap:Envelope>
3.2. Account 23
Gold-Link API Documentation, Release 0.0.6
The response has returned with a success result of true indicating the request was successful but also with a listattribute within the FindItemResult node. This list attribute indicates how many records have returned with aSUMMARY of Holdings Ltd.
There is no account with the name Holdings Ltd already in my Gold-Vision so the process to add a new Account cancontinue.
Updating an Account
In the event that a FindItem (List Items) request does return a list result set, it may be wise to update an existingAccount rather than add a new one. For this situation the FindItem (List Items) request above will return a responselike this:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><FindItemResponse xmlns="http://service.gold-vision.com/gold-link">
<FindItemResult><gvdata xmlns="">
<list records="1"><record id="72f46715-49f6-453c-8c63-201e0358459e
→˓" type="Account" ac_id="72f46715-49f6-453c-8c63-201e0358459e" summary="Holdings Ltd→˓"/>
</list></gvdata>
</FindItemResult><success>true</success><message/>
</FindItemResponse></soap:Body>
</soap:Envelope>
Using the record id from the response, a GetItem request can be used to return all the account information forHolding Ltd. The request will look like this:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:GetItem><gold:objectType>Account</gold:objectType><gold:id>72f46715-49f6-453c-8c63-201e0358459e</gold:id><gold:returnEmptyFields>false</gold:returnEmptyFields>
</gold:GetItem></soapenv:Body>
</soapenv:Envelope>
with the resulting response showing as:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><GetItemResponse xmlns="http://service.gold-vision.com/gold-link">
<GetItemResult><gvdata xmlns="">
24 Chapter 3. Gold-Vision Items
Gold-Link API Documentation, Release 0.0.6
<record objecttype="Account" id="72f46715-49f6-453c-→˓8c63-201e0358459e">
<field name="AC_ID" readOnly="true">72f46715-→˓49f6-453c-8c63-201e0358459e</field>
<field name="SUMMARY" label="Account Name"→˓details="">Holdings Ltd</field>
<field name="ACG_ID" type="uid" label="Security→˓" details="" id="78b6dbd2-8611-4e6d-9360-ddc40fe61066">Public</field>
<field name="AC_NUMBER" label="Account Number">→˓</field>
<field name="AC_POTENTIAL" readOnly="true"→˓label="Account Potential" type="numeric">0.00</field>
<field name="AC_SALES" readOnly="true" label=→˓"Account Sales" type="numeric">0.00</field>
<field name="AC_DISCOUNT" type="number" label=→˓"Discount">0.0E0</field>
<field name="NAME" label="Account Name">→˓Holdings Ltd</field>
<field name="AC_FLAG" type="uid" label="Support→˓Status" details="" mustHaveInsert="false" mustHaveUpdate="false" id="c2c40237-f662-→˓4f3d-913f-81e482fa4ca6">NEW CUSTOMER</field>
<field name="US_ID_SALES" type="uid" label=→˓"Account Manager" details="" id="a0833573-314a-49a8-b52a-569980821d94">Gold-Vision→˓Administrator</field>
<field name="US_ID_SUPPORT" type="uid" label=→˓"Support Manager" details="" id="">Not Assigned</field>
<field name="TYPE_1" type="uid" label="Esteiro→˓Relationship" details="" mustHaveInsert="false" mustHaveUpdate="false" id="">Not Set→˓</field>
<field name="TYPE_2" type="uid" label="Account→˓Type 2" details="" id="">Not Set</field>
<field name="LABEL" type="uid" label="Account→˓Type 3" id="">Not Set</field>
<field name="LEVEL" type="uid" label="Account→˓Type 4" id="">Not Set</field>
<field name="ACC_ID_SALES" type="uid" label=→˓"Primary Contact" details="" id="12422155-e45c-4ee7-b5dc-228f004425cf">Joe Bloggs</→˓field>
<field name="ACC_ID_SUPPORT" type="uid" label=→˓"Support Contact" id="">Not Assigned</field>
<field name="ADDRESS_1" label="Primary Address"→˓details="" mustHaveInsert="false" mustHaveUpdate="false">123 Old Street</field>
<field name="TOWN" label="Town/City" details=""→˓mustHaveInsert="false" mustHaveUpdate="false">London</field>
<field name="COUNTRY" label="Country" details="→˓">United Kingdom</field>
...</record>
</gvdata></GetItemResult><success>true</success><message/>
</GetItemResponse></soap:Body>
</soap:Envelope>
The resulting gvdata contains all the account information about Holdings Ltd including the ADDRESS_1 field ofwhich has a value of 123 Old Street.
3.2. Account 25
Gold-Link API Documentation, Release 0.0.6
To update this field to 321 New Street, an UpdateItem request can be made that will include the ADDRESS_1 field,like below:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:gold="http:/→˓/service.gold-vision.com/gold-link">
<soap:Header/><soap:Body>
<gold:UpdateItem><gold:objectType>Account</gold:objectType><gold:xmlData>
<gvdata xmlns=""><record><field name="ADDRESS_1">321 New Street</field></
→˓record></gvdata>
</gold:xmlData><gold:id>72f46715-49f6-453c-8c63-201e0358459e</gold:id><gold:overwrite>AllFieldsPresent</gold:overwrite>
</gold:UpdateItem></soap:Body>
</soap:Envelope>
Within Gold-Vision, the ADDRESS_1 field will have been updated from 123 Old Street to 321 New Street.
Creating a new Account
To create a new Account, a AddItem request can be made.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:AddItem><gold:objectType>Account</gold:objectType><gold:xmlData>
<gvdata xmlns=""><record><field name="SUMMARY">Holding Ltd</field><field name="NAME">Holding Ltd</field><field name="ADDRESS_1">321 New Street</field><field name="TOWN">London</field><field name="COUNTRY">United Kingdom</field></record></gvdata>
</gold:xmlData></gold:AddItem>
</soapenv:Body></soapenv:Envelope>
This request will create a new Account that will also have data set for it’s Primary Address, City/Town and Countryfields.
As a result, the response will return with the Account ID of the newly created Account and the following record willappear in Gold-Vision:
26 Chapter 3. Gold-Vision Items
Gold-Link API Documentation, Release 0.0.6
Contact
Looking at the Gold-Vision Model Diagram at the top of this page, it’s apparent that a Contact record is dependenton an Account record. Therefore, to create a Contact in Gold-Vision via Gold-Link, an AC_ID is required within therequest.
First, a FindItem (List Items) request can be made to get an AC_ID of an Account. The following request will add JoeBloggs to the Account Holdings Ltd.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:AddItem><gold:objectType>Contact</gold:objectType><gold:xmlData>
<gvdata xmlns=""><record>
<field name="AC_ID">72f46715-49f6-453c-8c63-→˓201e0358459e</field>
<field name="FIRSTNAME">Joe</field><field name="LASTNAME">Bloggs</field>
</record></gvdata>
</gold:xmlData></gold:AddItem>
</soapenv:Body></soapenv:Envelope>
The returnId node will contain the new ACC_ID of the new Contact.
Opportunity
An AC_ID is required with the AddItem request to create a new Opportunity. However, Opportunities, Activities,Projects, Quotes and Profiles also allow you to attach a Contact from the related Account. Although, this isn’t essentialand if no ACC_ID is provided, the Contact field will display as Not Assigned.
The process for creating an Opportunity with a Contact assigned will require you to make two FindItem (List Items)requests. The first will be to find the AC_ID of an Account and the second will be to find a Contact’s ACC_ID that
3.3. Contact 27
Gold-Link API Documentation, Release 0.0.6
has that also has this AC_ID. An AddItem request can then be made to create an Opportunity with an AC_ID and anACC_ID. The request will look like this:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:AddItem><gold:objectType>Opportunity</gold:objectType><gold:xmlData>
<gvdata xmlns=""><record>
<field name="AC_ID">72f46715-49f6-453c-8c63-→˓201e0358459e</field>
<field name="SUMMARY">Sales Opportunity</field><field name="ACC_ID">12422155-e45c-4ee7-b5dc-
→˓228f004425cf</field></record></gvdata>
</gold:xmlData></gold:AddItem>
</soapenv:Body></soapenv:Envelope>
The returnId node will contain the new OP_ID of the new Opportunity and the following record will appear withinyour Gold-Vision:
Events/Seminars
For this example a Seminar Session Attendee will be added into Gold-Vision. Looking at the Gold-Vision ModelDiagram, it is apparent that there are a lot of requirements for a Seminar Session Attendee to exist.
First, an AddItem request will be made to create a Seminar.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
28 Chapter 3. Gold-Vision Items
Gold-Link API Documentation, Release 0.0.6
<gold:AddItem><gold:objectType>Seminar</gold:objectType><gold:xmlData>
<gvdata xmlns=""><record>
<field name="SUMMARY">Sales Demo</field><field name="AC_ID">72f46715-49f6-453c-8c63-
→˓201e0358459e</field></record></gvdata>
</gold:xmlData></gold:AddItem>
</soapenv:Body></soapenv:Envelope>
This request will create a Seminar called ‘Sales Demo’ for the Account ‘Holding Ltd’. The AC_ID is an optional field.
Now there is a Seminar, the next step would be to create a Seminar Session for our attendee to attend. This is therequest that will be made:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:AddItem><gold:objectType>SeminarSession</gold:objectType><gold:xmlData>
<gvdata xmlns=""><record>
<field name="SUMMARY">Morning Session</field><field name="SEM_ID">687bf90e-a4a3-44fa-8502-
→˓145605d61243</field><field name="PLACES">10</field>
</record></gvdata>
</gold:xmlData></gold:AddItem>
</soapenv:Body></soapenv:Envelope>
Note: A Seminar Session only requires a SUMMARY and SEM_ID. However, in order to make a Seminar Booking,the Seminar Session is required to have places available. Therefore, I have created a Seminar Session that has 10places available to allow for bookings to take place.
Now there is a Seminar Session, again by looking at the Gold-Vision Model Diagram, it is apparent that the only otherdependency for a Seminar Session Attendee is the existence of a Seminar Booking Attendee.
Before a Seminar Booking Attendee can be made, a Seminar Booking is required to exist. This request will create aSeminar Booking in Gold-Vision:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:AddItem><gold:objectType>SeminarBooking</gold:objectType>
3.5. Events/Seminars 29
Gold-Link API Documentation, Release 0.0.6
<gold:xmlData><gvdata xmlns=""><record>
<field name="SEM_ID">687bf90e-a4a3-44fa-8502-→˓145605d61243</field>
<field name="SEMS_ID">d83a773d-32a3-4127-afbf-→˓e66695600ecc</field>
<field name="AC_ID">72f46715-49f6-453c-8c63-→˓201e0358459e</field>
<field name="REFERENCE">SES001</field></record></gvdata>
</gold:xmlData></gold:AddItem>
</soapenv:Body></soapenv:Envelope>
Note: Although the request has been successful, for a Seminar Booking to appear in Gold-Vision, it needs to havea Seminar Booking Attendee. However, a Seminar Booking Attendee request cannot be made beforehand as it isrequired to have a SEMB_ID.
The next step to be made will be to create a Seminar Booking Attendee for the Seminar Booking that has just beencreated:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:AddItem><gold:objectType>SeminarBookingAttendee</gold:objectType><gold:xmlData>
<gvdata xmlns=""><record>
<field name="SEMB_ID">828048a9-2f39-4cae-a065-→˓3c0da64c6353</field>
<field name="AC_ID">72f46715-49f6-453c-8c63-→˓201e0358459e</field>
<field name="ACC_ID">12422155-e45c-4ee7-b5dc-→˓228f004425cf</field>
</record></gvdata>
</gold:xmlData></gold:AddItem>
</soapenv:Body></soapenv:Envelope>
The above request has now created a Seminar Booking Attendee using the Contact ‘Joe Bloggs’. The required fieldsfor this request are SEMB_ID and AC_ID. If no ACC_ID is provided, the Seminar Booking Attendee will be addedas ‘Anonymous’.
Now that all the prerequisites are met, a final request can be made to add a new Seminar Session Attendee. This is therequest that will be made:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/>
30 Chapter 3. Gold-Vision Items
Gold-Link API Documentation, Release 0.0.6
<soapenv:Body><gold:AddItem>
<gold:objectType>SeminarSessionAttendee</gold:objectType><gold:xmlData>
<gvdata xmlns=""><record>
<field name="SEMBA_ID">ddf4dbcd-53af-4b6e-aef8-→˓bf55f6ff7ab8</field>
<field name="SEMS_ID">d83a773d-32a3-4127-afbf-→˓e66695600ecc</field>
</record></gvdata>
</gold:xmlData></gold:AddItem>
</soapenv:Body></soapenv:Envelope>
A Seminar Session Attendee will now appear in your Gold-Vision like below:
Phone Systems
LogCall
It is possible to log incoming and outgoing telephone calls within Gold-Vision using Gold-Link. To do so, a LogCallrequest can be made like below:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:LogCall><gold:accountId>71fb89cb-92ad-4973-8293-d43f1cd98673</
→˓gold:accountId><gold:contactId>ca194711-f378-48c4-88f2-b8ae22207091</
→˓gold:contactId><gold:number>01234 567890</gold:number>
3.6. Phone Systems 31
Gold-Link API Documentation, Release 0.0.6
<gold:inbound>true</gold:inbound></gold:LogCall>
</soapenv:Body></soapenv:Envelope>
This request will return a result with a success node and a message node. If success appears as ‘false’, themessage node will display the error that caused the request to fail.
Note: It is possible to send this request without a contactId value. By leaving this node empty, a telephone callwill be entered into Gold-Vision against the given Account rather than against a Contact.
LogCallWithDuration
An extension to the LogCall request is to make a LogCallWithDuration request that includes additional data toindicate how long the telephone call had lasted.
This is what a LogCallWithDuration request will look like:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:LogCallwithDuration><gold:accountId>71fb89cb-92ad-4973-8293-d43f1cd98673</
→˓gold:accountId><gold:contactId>ca194711-f378-48c4-88f2-b8ae22207091</
→˓gold:contactId><gold:number>01234 567890</gold:number><gold:inbound>true</gold:inbound><gold:duration>3</gold:duration>
</gold:LogCallwithDuration></soapenv:Body>
</soapenv:Envelope>
This request adds an inbound telephone call against the Contact Joe Bloggs and Account Holding Ltd as well asgiving the record a duration value of 3.
LookupPhoneNumber
This request is useful when looking to return all matching Contacts and Accounts with the input of a telephone number.The request will look similar to this:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"→˓xmlns:gold="http://service.gold-vision.com/gold-link">
<soapenv:Header/><soapenv:Body>
<gold:LookupPhoneNumber><gold:number>01234 567890</gold:number>
</gold:LookupPhoneNumber></soapenv:Body>
</soapenv:Envelope>
32 Chapter 3. Gold-Vision Items
Gold-Link API Documentation, Release 0.0.6
The response will return a list node that will contain both account and contact records if any match thetelephone number sent with the original request. This is the sort of response that you are likely to receive:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=→˓"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/→˓XMLSchema">
<soap:Body><LookupPhoneNumberResponse xmlns="http://service.gold-vision.com/gold-
→˓link"><LookupPhoneNumberResult>
<gvdata xmlns=""><list>
<account id="71fb89cb-92ad-4973-8293-→˓d43f1cd98673">
<ac_name>Holding Ltd</ac_name><ac_id>71fb89cb-92ad-4973-8293-
→˓d43f1cd98673</ac_id><ac_phone/><ac_link>http://gvsandbox01/Gold-
→˓VisionThorne/goldvision.aspx?page=popthru&killwindow=1&action=OpenAccount&→˓amp;actiondata=71fb89cb-92ad-4973-8293-d43f1cd98673</ac_link>
<contacts><contact id="ca194711-f378-48c4-
→˓88f2-b8ae22207091"><acc_name>Joe Bloggs</acc_name><acc_id>ca194711-f378-48c4-
→˓88f2-b8ae22207091</acc_id><acc_phone>01234 567890</acc_
→˓phone><acc_mobile/><acc_link>http://gvsandbox01/
→˓Gold-VisionThorne/goldvision.aspx?page=popthru&killwindow=1&→˓action=OpenContact&actiondata=ca194711-f378-48c4-88f2-b8ae22207091</acc_link>
<acc_match>true</acc_match></contact>
</contacts></account>
</list></gvdata>
</LookupPhoneNumberResult><success>true</success><message/>
</LookupPhoneNumberResponse></soap:Body>
</soap:Envelope>
3.6. Phone Systems 33
Gold-Link API Documentation, Release 0.0.6
34 Chapter 3. Gold-Vision Items
CHAPTER 4
Code Samples
Javascript
First a XML HTTP request object will be generated and the API endpoints will be declared as follows:
var http_glink = null;var soap_ns = 'http://service.gold-vision.com/gold-link'var soap_get_version = '"'+soap_ns+'/GetVersion"';var soap_find_item = '"'+soap_ns+'/FindItem"';var soap_get_item = '"'+soap_ns+'/GetItem"';var soap_add_item = '"'+soap_ns+'/AddItem"';var soap_update_item = '"'+soap_ns+'/UpdateItem"';var soap_get_drop_options = '"'+soap_ns+'/GetDropOptions"';
// This generates an XML Http request objectfunction glink_getXmlHttp() {
try {var req;try { req = new XMLHttpRequest(); }catch (e2) {
try { req = new ActiveXObject("Msxml2.XMLHTTP"); }catch(e3) {
try { req = new ActiveXObject("Microsoft.XMLHTTP"); }catch (e4) { req = false; }
}}return req;
} catch(e) { alert('Error: ' + e.message); }}
Then, create the object that will be executed to make the request. It will take in a SOAP Action and return with theresponse. This is what it will look like:
function glink_execute(soapAction, soapXml, callBackFunction) {var s = '';
35
Gold-Link API Documentation, Release 0.0.6
s += '<?xml version="1.0" encoding="utf-8"?>';s += '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
→˓xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/→˓soap/envelope/">';
s += ' <soap:Body>';// Soap datas += soapXml;s += ' </soap:Body>';s += '</soap:Envelope>';// Process requesthttp_glink = this.getXmlHttp();http_glink.open('POST', this.url + '?z=' + new Date().getTime(), true);http_glink.setRequestHeader("Content-Type", "text/xml; charset=utf-8");http_glink.setRequestHeader("Content-Length", s.length);http_glink.setRequestHeader("SOAPAction", soapAction);http_glink.onreadystatechange = function() {
if (http_glink.readyState == 4) {if (http_glink.status == 200)
callBackFunction(http_glink.responseXML);else if (http_glink.status == 500)
alert("500 - Server error!");else if (http_glink.status == 404)
alert("404 - Service not found!");else
alert("Unexpected status: " + http_glink.status);}
}http_glink.send(s);}
Now, create our functions to make the SOAP requests. For example, a FindItem (List Items) request will look like this:
function glink_findItem(objectType, filterParams, extraFields, callBackFunction) {// Build findvar s = '';s += '<FindItem xmlns="'+soap_ns+'">';s += '<objectType>'+objectType+'</objectType>';s += '<XmlFilters><filters xmlns="">';for (i = 0; i < filterParams.length; i++)
s += '<filter dbcolumn="'+filterParams[i]["dbcolumn"]+'" type="→˓'+filterParams[i]["type"]+'" value="'+filterParams[i]["value"]+'" />';
for (i = 0; i < extraFields.length; i++)s += '<field dbcolumn="'+extraFields[i]["dbcolumn"]+'" />';
s += '</filters></XmlFilters>';s += '</FindItem>';// Send to Gold-Linkthis.execute(soap_find_item, s, callBackFunction);
}
Finally, this function simply associates the above functions with the ‘glink’ object.
function glink(url) {// This simply associates the above functions with the 'glink' object
this.url = url;this.execute = glink_execute;this.findItem = glink_findItem;
this.getItem = glink_getItem;this.addItem = glink_addItem;
36 Chapter 4. Code Samples
Gold-Link API Documentation, Release 0.0.6
this.updateItem = glink_updateItem;this.getDropOptions = glink_getDropOptions;this.getXmlHttp = glink_getXmlHttp;
}
Note: A Javascript example that interacts with the Gold-Link API can be found here: .
PHP
First, a PHP file that contains the authentication details of the SOAP request will be created. This file will be calledGVGoldLinkNTLM.php.
<?phpclass GVGoldLinkNTLMSoapClient extends NTLMSoapClient {
protected $user = 'DOMAIN\USERNAME';protected $password = 'PASSWORD';
}?>
Now, the creation of a method for making the requests will exist in a separate file. The following request will becontained within a PHP file called NTLMSoapClient.php:
<?phpclass NTLMSoapClient extends SoapClient {
function __doRequest($request, $location, $action, $version) {
$headers = array('Method: POST','Connection: Keep-Alive','User-Agent: PHP-SOAP-CURL','Content-Type: text/xml; charset=utf-8','SOAPAction: "'.$action.'"',
);//echo $request;$this->__last_request_headers = $headers;$ch = curl_init($location);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);curl_setopt($ch, CURLOPT_POST, true );curl_setopt($ch, CURLOPT_POSTFIELDS, $request);curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_NTLM);curl_setopt($ch, CURLOPT_USERPWD, $this->user.':'.$this->password);$response = curl_exec($ch);
return $response;}
function __getLastRequestHeaders() {return implode("\n", $this->__last_request_headers)."\n";
}}
?>
4.2. PHP 37
Gold-Link API Documentation, Release 0.0.6
Request can now be made using PHP. The following example will make a GetVersion Gold-Link request:
<!DOCTYPE html><html><head>
<title>GoldLink with PHP - Basic Examples</title></head><body>
<h3>GoldLink with PHP - Basic Examples</h3><?php
// Include the required classesinclude 'GVGoldLinkNTLM.php';
// The URL of the WSDL file for Gold-Link$url = 'http://' . $GVAddress . '/gold-link/goldlink.asmx?wsdl';
// Unregister the current HTTP wrapperstream_wrapper_unregister('http');
// Register the new HTTP wrapperstream_wrapper_register('http', 'GVGoldLinkNTLMStream') or die(
→˓"Failed to register protocol");
// Now, all requests to a http page will be done by→˓GVGoldLinkNTLMStream.
// Instantiate the client$GVGLclient = new GVGoldLinkNTLMSoapClient($url);
//Gold-Vision Version$GVVersion = $GVGLclient->GetVersion()->{'GetVersionResult'};echo '<p>GV Version: '.$GVVersion.'</p>';
// Restore the original HTTP stream wrapperstream_wrapper_restore('http');
?></body>
</html>
Note: A PHP example that interacts with the Gold-Link API can be found here: .
C#
For this code example, I have used the Add Web Reference feature within Visual Studio. This then allows me tocreate a Data Access model that handles the authentication and method calls.
A model called GVDataModel will be created and it will contain the following structure:
public class GVDataModel{
#region Enums
#region Filters
#region Fields
38 Chapter 4. Code Samples
Gold-Link API Documentation, Release 0.0.6
private local.esteiro.goldlink gL;
#region Constructors
#region Private Methods
#region Public Methods}
Enums
This region is designed to contain various enumerators to make things easier when dealing with large amounts of data.The following is an example of an enumerator that could be used within Gold-Link.
public enum FilterType{
Day = 0,Week = 1,None = 2
}
Filters
This region is designed to contain all of your Filter elements that will be used later within your Private and Publicmethods. The following is an example of a ‘sortBy’ filter that will either filter by CREATED_DATE or DUE_DATE.
private XElement sortBy(SortType sortType){
switch (sortType){
case SortType.CreatedDate: return new XElement(
"sort",new XAttribute[]
{new XAttribute("dbcolumn", "CREATED_DATE"),new XAttribute("order", "ascending")
});case SortType.DueDate: return new XElement(
"sort",new XAttribute[]
{new XAttribute("dbcolumn", "DUE_DATE"),new XAttribute("order", "ascending")
});default: return new XElement(
"sort",new XAttribute[]{
new XAttribute("dbcolumn", "DUE_DATE"),
4.3. C# 39
Gold-Link API Documentation, Release 0.0.6
new XAttribute("order", "ascending")}
);}
}
Fields
This region is designed to contain all of the fields that you wish to include when making certain requests such asAddItem.
private XElement Summary(){
return new XElement(
"field",new XAttribute[]
{new XAttribute("dbcolumn", "SUMMARY"),
});
}
Constructors
This is the most important part of your model. This is where the Gold-Link connection is constructed and where theauthentication is made.
The following example is dependent on the Gold-Link URL, Gold-Link Domain, Gold-Link User and Gold-LinkPassword being set within your application’s configuration file.
public GVDataModel(){
this.gL = new mycompany.goldlink();this.gL.Url = Properties.Settings.Default.mycompany_goldlink;if (string.IsNullOrEmpty(Properties.Settings.Default.GoldLinkUser)){
gL.UseDefaultCredentials = true;}else{
this.gL.UseDefaultCredentials = false;NetworkCredential gLCred = new NetworkCredential();gLCred.UserName = Properties.Settings.Default.GoldLinkUser;gLCred.Domain = Properties.Settings.Default.GoldLinkDomain;gLCred.Password = Properties.Settings.Default.GoldLinkPassword;this.gL.Credentials = gLCred;
}}
Private Methods
This is where most of the actual Gold-Link requests will be made.
40 Chapter 4. Code Samples
Gold-Link API Documentation, Release 0.0.6
private List<Activity> getActivities(SortType sortType){
List<Activity> tActivities = new List<Activity>();
//Resultsstring result;bool success;
//XML FiltersXElement XmlFilters =
new XElement(
"filters",new Object[]
{new XAttribute("xmlns",""),sortBy(sortType),Summary()
});
//ResultXmlNode XmlResult = gL.FindItem(GoldLink.ObjectType.AccountActivity,
→˓CreateXmlNode(XmlFilters), out success, out result);XmlNode listElement = XmlResult.FirstChild;
//Loop through returned Xml and storeforeach (XmlElement child in listElement.ChildNodes){
tActivities.Add(
new Activity(
child.Attributes.GetNamedItem("id").Value,child.Attributes.GetNamedItem("summary").Value,DateTime.Parse(child.Attributes.GetNamedItem("due_
→˓date").Value))
);}return tActivities;
}
Public Methods
Finally, the Public Methods section will contain the list of methods available to call within your application.
public Dictionary<string, string[]> ActivtyReturn(){
Dictionary<string, string[]> ActivityList = new Dictionary<string,→˓string[]>();
List<Activity> oActivity = new List<Activity>();
try{
oActivity = getActivities();
4.3. C# 41
Gold-Link API Documentation, Release 0.0.6
}catch (Exception e){
}
string[] activ = new string[] { };int i = 0;
foreach (Activity oAct in oActivity){
activ[i] = oAct.summary;i++;
}
return ActivityList;}
42 Chapter 4. Code Samples