Other Integrations: Salesforce

Salesforce

Catch-e contains a number of fields and flags that enable https://salesforce.com/au to be interfaced using web services.

For new integrations with Salesforce, Catch-e recommends and prefers the apex method.

The processes and functionality used to provide a salesforce interface can be applied to other CRM packages as required.

You can provide your prospective CRM providers with a high-level Salesforce Guide about the integration services that are available to do this. Your Account Manager can then help you further on engagement.

Examples of the functionality a CRM interface can provide are listed below:

• Transfer quote and product information
• Transfer any changes or updates to quotes
• Call for and use Catch-e documents in your CRM system

Salesforce key fields

The following fields in Catch-e have been created for using in a salesforce interface.

Fleet / Administration / Quotes / Header → "Opportunity No"

Fleet / Administration / Quotes / Contract → "Opportunity ID"

Fleet / Administration / Quotes / Contract → "Opportunity Number"

Fleet / Administration / Suppliers / Detail → "External Code"

Create a WSDL File Type

A new file type record and directory needs to be created in by Catch-e staff. The directory path for this is '/clients/{client}/core/fleet/lib/interfaces/wsdls'

Add a WSDL File

To add or update the WSDL this feature requires:

1. Navigate to the Setup / Import/Export Files menu.

2. Choose the file type 'Salesforce WSDLs'

3. Choose the WSDL file that is applicable to the environment you are working in. E.g. 'salesforce-test.wsdl', 'salesforce-staging.wsdl' or 'salesforce-live.wsdl'.

4. Upload the file.

Global Controls

If you are using the Apex Salesforce APIs, update the Global Controls listed below;

Apex API Permissions

Check that the required API permissions are set-up to use the Salesforce_Apex APIs

select *from gb_api_permissionsWHERE permission = 'InterfaceSalesforceApex:SyncQuote';select r.name,r.access_type,rap.*from gb_role_api_permissions AS rapinner join gb_roles AS r ON r.role_id = rap.role_idWHERE permission = 'InterfaceSalesforceApex:SyncQuote';

Apex API Error Codes

| 9 | 500 | | Sales Apex Sync Quote failed Unable to perform this action! Please try again.

If the problem persists please contact your system administrator.

Error:
Array | "Opportunity Number" is 0 |

apexrest/syncquote

This call is triggered when the following functions are run in Catch-e

1. Create
2. Save
3. Apply
4. Accept

The Quotes / Contract "Salesforce By" field shows the call timestamp and response.

Suppression

The call is suppressed if

1. The API createQuoteWebService is used to create a quote
2. copyQuote) is used to copy a quote.

When the call has been supressed, the Quotes / Contract "Salesforce By" field will be blank.

apexrest/synccontract

This call is triggered when the following functions are run in Catch-e

1. Accept Quote
2. Copy Contract
3. Edit Contract
4. Create, Edit or Delete a Contract Event (where Event triggers an update to Contract data. E.g. Driver Change)

This call is not triggered when the following functions are run in Catch-e

1. Contracts / Finance Apply button is clicked
2. Contracts / Finance Get Application Status button is clicked
3. Contracts / Finance Get Documents button is clicked
4. Scheduler / Job executeScript) updates

The call is suppressed if a contract is edited by running the API Insert or update a record with auditing.

Global Controls

If you are using the Salesforce legacy web services, update the Global Controls listed below.

When configured, the API Sync quote with Salesforce (legacy) interface_interface) can be used.

Processing the queue (SOAP method)

When a Quote or Contract is saved, a transaction record is inserted into the table with a 'queued' timestamp equal to the timestamp the Quote or Contract was saved. This queue is processed one transaction at a time from oldest to newest.

The process will follow these steps:

1. Logs in to Salesforce to get session token if a current session token has not been cached. Session Tokens timeout after 8 hours. If a session token is still current, it will be re-used avoiding the need to login in which case this step will be skipped.

2. Sleep for 1 second

3. Performs Update Opportunity in Salesforce

4. Performs Update History for Opportunity in Salesforce

Repeat for next transaction in the queue.

Processing the queue using SQS FIFO (SOAP method)

When a Quote of Contract is saved, a transaction record is inserted into the SQS FIFO queue.

Queued Salesforce operations will contain a MessageGroupId with the following formats:

• qt:salesforce?opportunityid=OPPORTUNITYID

• qt:salesforce?contractid=CONTRACTID

• qt:salesforce?quoteid=QUOTEID

Messages containing the same MessageGroupId will be processed in FIFO order. Messages that belong to the same message group are always processed one by one, in a strict order relative to the message group.

Queued Salesforce operations will also contain a MessageDeduplicationId with the following formats:

• qt:salesforce:updateOpportunityFromContract/{serialized-parameters}

• qt:salesforce:updateQuotationHistoryVehicleOptions/{serialized-parameters}

• qt:salesforce:updateOpportunityFromQuote/{serialized-parameters}

If a message with a particular message deduplication ID is sent successfully, any messages sent with the same message deduplication ID are accepted successfully but will not be delivered during the 1-minute deduplication interval. This is to prevent frequent updates for the same opportunity/contract from impacting queue worker processing.

For full technical details please refer to original specification here.

A note regarding patchQuote

Warning: Please note that a patchQuote request will NOT trigger data to be pushed to Salesforce. If you need the data updated in the patchQuote request to be sent to Salesforce please use the API 'salesforceLegacySyncQuote'.

Sync quote with Salesforce legacy interface

This API is used in the legacy integration of Salesforce with Catch-e.

For new integrations with Salesforce, Catch-e recommends and prefers the apex method.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on InterfaceSalesforceLegacy:SyncQuote.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

Input Fields (Header)

• Header should contain the 'accept' Key with the Value = 'application/problem+json' or application/vnd.catch-e-api.v1+json.

Input Fields (Body)

URL Examples

https://api.catch-e.com/gb/interface/salesforce-legacy/sync-quote

Response Details

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Go to System Roles and enter 'web_services' Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 422 - Unprocessable Entity | | |

{ "validation_messages": { "message for this task } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}

| Explanation for this message. |
| 423 - Locked | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Locked", "status": 423, "detail": "Locked"}

| If one of the records in the JSON Body is already being edited, the entire batch will fail and show this message. |
| 500 - Unexpected error | | |

{ "status": 500, "title": "Unexpected error", "describedBy": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "detail": "JSON encoding error occurred: Malformed UTF-8 characters, possibly incorrectly encoded",}

| If a query has encrypted fields which are not decrypted using aes_decrypt in JSON response, below error is thrown. Please decrypt the fields in query before adding the query in table. |

AutoGuru Vehicle Export

Go to the AutoGuru page for details about all of the jobs, the process and for set-up steps.

Business Rules for exporting vehicles (contract and vehicle data) to AutoGuru from Catch-e

Records are exported via scheduled AutoGuru jobs.

Selection Criteria

1. Contract Types / Details "Autoguru Export" - is checked
2. Contracts / Contract "Reg Number" - is not 'ORDER'
3. Contracts / Contract "Contract Start" - is today or earlier
4. Contracts / Contract "Suspend Date" - is blank or after today
5. Contracts / Vehicle "Autoguru Export" - is checked
6. Contracts / Vehicle "Build Date" is in a suitable report format
7. Contracts / Vehicle "VIN" - if populated, it is 17 characters long and is not duplicated on another selected contract. It can be blank.
8. Contracts / Vehicle "Manufacturer Name" - does not contain commas
9. Contracts / Vehicle "Model Name" - does not contain commas

Odometer, Expenses and Budgets data are selected based on following conditions

1. Odometer: A valid Odometer record with = 'posted' or 'history-only'
2. Expenses: An expense record with = 'posted' or 'history-only' AND linked = 'yes'
3. Budgets: A budget record with = 'posted' AND on or before end of current month AND linked = 'yes'

| Lease Type | If Contract Types / Details "Group" is not 'Lease' or 'Novated', show as '0' If Contract Types / Details "Group" is 'Lease', show as '1' If Contract Types / Details "Group" is 'Novated', show as '2' | | | DriverBalanceIncGST | If Contract Types / Details "Group" is not 'Lease' or 'Novated' this is set as 0.00. Calculation: Total of invoiced budgets − Total of maintenance costs

Record selection
Only budgets and costs where Posting Classes "Autoguru Export" is checked are selected (by design, only 'M', 'MAINT', 'S' and 'T' classes should be set to 'yes'.) Invoiced budgets are dated on or before today and are in 'Posted' status Maintenance cost records have not been recharged and are in 'Posted' or 'History Only' status
| TyreBalance | If Contract Types / Details "Group" is 'Novated' show as '99' Otherwise return "Tyre Allowance" less "Tyres Used". Contract Header "Tyres?" shows these two numbers. Contracts / Contract "Tyre Allowance" holds the allowance count. Go to the Tyre Allowance page for more details. | |

AutoGuruDailyBookingFileStructure

Daily Booking File Data Structure and Mapping