Gold-Link API¶

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 by sending 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 interoperability. The recommended choice on a Windows platform is to use .NET Framework and on a Linux platform is to use PHP.

Note

If using .NET Framework, the Gold-Vision API web service can be automatically integrated using the Visual Studio “Add Web Reference” option. More information on how to use this feature can be found here - Microsoft Visual Studio - Add Web Reference.

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 support@gold-vision.com 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

Note

The Gold-Vision API is built into individual implementations and therefore the URL will be unique for a particular 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 match that 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.1
    Host: example.goldvisioncrm.com
    Content-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 OK
    Content-Type: application/soap+xml; charset=utf-8
    Content-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">
            <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 solution such as SoapUI.

By using a solution such as SoapUI, you are able to send requests to Gold-Link and observe the responses within a user friendly user interface.

Note

Throughout the rest of this documentation, all of the SOAP requests and responses have been generated using a 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 will be 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 within the Administration Console. The file containing the Gold-Link errors will be labelled as Gold-Link_{date}.txt.

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	Type
Empty	N/A

Response

Attribute	Type
GetVersionResult	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:

<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 and sort nodes provided.

Request

Attribute (Required/Optional)

Type

objectType

ObjectType

filters

<filter dbcolumn=”” value=”” type=”“></filter>

<rowlimit value=”“></rowlimit>

<sort dbcolumn=”” order=”“></sort>

</filters>

Response

Attribute	Type
FindItemResult	List
success	Boolean
message	String

For a FindItem request, you will be required to send an objectType and filters node. The following nodes can be 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 all Accounts 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>
   </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 all Accounts 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 request will 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 sorted in 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>

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)	Type
objectType	ObjectType
id	String
returnEmptyFields	Boolean

Response

Attribute	Type
GetItemResult	XML
success	Boolean
message	String

To make a request using GetItem, you will be required to make a request with an objectType, id and returnEmptyFields 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>
       </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)	Type
objectType	ObjectType
xmlData	XML

Response

Attribute	Type
AddItemResult	Boolean
returnId	String
success	Boolean
message	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 a new Account with just a SUMMARY value and nothing else. To create a new Account with more data, you will be required 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	ObjectType
xmlData	XML
id	String
overwrite	AllFieldsPresent or AllFieldsPresentExceptBlanks or AllFieldsPresentExceptBlanksWhereTargetEmpty

Response

Attribute	Type
UpdateItemResult	Boolean
success	Boolean
message	String

To make a request using UpdateItem, you will be required to make a request with an objectType, xmlData, id and overwrite node. The overwrite node can either have a value of AllFieldsPresent, AllFieldsPresentExceptBlanks 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 in Gold-Vision.

Request

Attribute (Required/Optional)	Type
objectType	ObjectType

Response

Attribute	Type
GetObjectDefResult	XML
success	Boolean
message	String

The GetObjectDef request only requires you to include the objectType node with the request. From this, a response will be returned that includes ObjectDef information related to the value included in objectType such as field names and 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"/>
                               <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 is successful or not.

GetDropOptions¶

This method is useful when getting a list of the available dropdown values for a dropdown field.

Attribute (Required/Optional)	Type
objectType	ObjectType
fieldName	String

Response

Attribute	Type
GetDropOptionsResult	List
success	Boolean
message	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 is labelled 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=""/>
                               <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 have to 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)	Type
objectType	ObjectType
id	String

Response

Attribute	Type
DeleteItemResult	Boolean
success	Boolean
message	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.

Attribute (Required/Optional)	Type
accountId	String
contactId	String
number	String
inbound	Boolean

Response

Attribute	Type
LogCallResult	Boolean
success	Boolean
message	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’, the message 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 call will 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)	Type
accountId	String
contactId	String
number	String
inbound	Boolean
duration	Integer

Response

Attribute	Type
LogCallwithDurationResult	Boolean
success	Boolean
message	String

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 as giving 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)	Type
number	String

Response

Attribute	Type
LookupPhoneNumberResult	Boolean
success	Boolean
message	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 the telephone 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&amp;killwindow=1&amp;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&amp;killwindow=1&amp;action=OpenContact&amp;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>

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 a new Contact will require you to pass an AC_ID of an existing Account in the request.

Core Items¶

Seminars¶

Things can become a little more difficult if creating a new Seminar Session Attendee record compared to a simple Contact record. By looking at the above diagram, creating a new Seminar Session Attendee record in Gold-Vision requires you to have a Seminar Session and a Seminar Booking Attendee. However, the Seminar Session requires a Seminar. Also, the Seminar Booking Attendee is dependent on a Seminar Booking of which is dependent on a Seminar and an Account.

Therefore, creating a Seminar Session Attendee record requires you to have a Seminar Session, Seminar Booking Attendee, 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 Campaign mode 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 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: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>

The response has returned with a success result of true indicating the request was successful but also with a list attribute within the FindItemResult node. This list attribute indicates how many records have returned with a SUMMARY 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 can continue.

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 existing Account rather than add a new one. For this situation the FindItem (List Items) request above will return a response like 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 for Holding 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="">
                               <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 of which has a value of 123 Old Street.

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 Country fields.

As a result, the response will return with the Account ID of the newly created Account and the following record will appear in Gold-Vision:

Contact¶

Looking at the Gold-Vision Model Diagram at the top of this page, it’s apparent that a Contact record is dependent on an Account record. Therefore, to create a Contact in Gold-Vision via Gold-Link, an AC_ID is required within the request.

First, a FindItem (List Items) request can be made to get an AC_ID of an Account. The following request will add Joe Bloggs 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 essential and 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 has that also has this AC_ID. An AddItem request can then be made to create an Opportunity with an AC_ID and an ACC_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 within your Gold-Vision:

Events/Seminars¶

For this example a Seminar Session Attendee will be added into Gold-Vision. Looking at the Gold-Vision Model Diagram, 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>
              <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 the request 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 10 places 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 other dependency 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 a Seminar 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>
                     <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 have a Seminar Booking Attendee. However, a Seminar Booking Attendee request cannot be made beforehand as it is required 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 been created:

<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 fields for this request are SEMB_ID and AC_ID. If no ACC_ID is provided, the Seminar Booking Attendee will be added as ‘Anonymous’.

Now that all the prerequisites are met, a final request can be made to add a new Seminar Session Attendee. This is the request 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>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 LogCall request 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>
                     <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’, the message 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 call will 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 to indicate 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 as giving 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>

The response will return a list node that will contain both account and contact records if any match the telephone 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&amp;killwindow=1&amp;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&amp;killwindow=1&amp;action=OpenContact&amp;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>

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 object
function 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 the response. This is what it will look like:

function glink_execute(soapAction, soapXml, callBackFunction) {
    var s = '';
    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 data
    s += soapXml;
    s += '  </soap:Body>';
    s += '</soap:Envelope>';
    // Process request
    http_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 find
            var 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-Link
            this.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;
            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: Javascript Example.

PHP¶

First, a PHP file that contains the authentication details of the SOAP request will be created. This file will be called GVGoldLinkNTLM.php.

<?php
class 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 be contained within a PHP file called NTLMSoapClient.php:

<?php
class 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";
    }
}
    ?>

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 classes
                    include 'GVGoldLinkNTLM.php';

                    // The URL of the WSDL file for Gold-Link
                    $url = 'http://' . $GVAddress . '/gold-link/goldlink.asmx?wsdl';

                    // Unregister the current HTTP wrapper
                    stream_wrapper_unregister('http');

                    // Register the new HTTP wrapper
                    stream_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 wrapper
                    stream_wrapper_restore('http');
            ?>
    </body>
</html>

Note

A PHP example that interacts with the Gold-Link API can be found here: PHP Example.

C#¶

For this code example, I have used the Add Web Reference feature within Visual Studio. This then allows me to create 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

            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 Public methods. 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"),
                                    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 as AddItem.

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 the authentication is made.

The following example is dependent on the Gold-Link URL, Gold-Link Domain, Gold-Link User and Gold-Link Password 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.

private List<Activity> getActivities(SortType sortType)
    {
            List<Activity> tActivities = new List<Activity>();

            //Results
            string result;
            bool success;

            //XML Filters
            XElement XmlFilters =
                    new XElement
                    (
                            "filters",
                            new Object[]
                    {
                            new XAttribute("xmlns",""),
                            sortBy(sortType),
                            Summary()
                    }
                    );

            //Result
            XmlNode XmlResult = gL.FindItem(GoldLink.ObjectType.AccountActivity, CreateXmlNode(XmlFilters), out success, out result);
            XmlNode listElement = XmlResult.FirstChild;

            //Loop through returned Xml and store
            foreach (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();
            }
            catch (Exception e)
            {

            }

            string[] activ = new string[] { };
            int i = 0;

            foreach (Activity oAct in oActivity)
            {
                    activ[i] = oAct.summary;
                    i++;
            }

            return ActivityList;
    }