A How To guide for integrating your application to the CRM Hub

Transcription

1 A How To guide for integrating your application to the CRM Hub Last Update: 28 January 2014

2 2 Table of Contents TABLE OF CONTENTS INTRODUCTION DEFINITIONS SIGN UP FOR AN CLOUD ELEMENTS ACCOUNT PROVISIONING CUSTOMER ACCOUNTS FOR AN ELEMENT PROVISIONING A CUSTOMER ACCOUNT FOR AN ELEMENT VIA THE ELEMENTS MANAGER PROVISION A CUSTOMER ACCOUNT FOR AN ELEMENT VIA THE API PROVISION THE CUSTOMER ACCOUNT INSTANCE USE YOUR PROVISIONED CUSTOMER ACCOUNT ONLINE DOCUMENTATION GET MORE SUPPORT Introduction The Cloud Elements CRM Hub provides a uniform API to quickly provide the functionality within your application to manage CRM leads, opportunities, contacts, and accounts, as well as adding notes to those objects. It can do this across multiple venders, such as SugarCRM and Salesforce.com. Future plans include Microsoft Dynamics, Zoho CRM, Highrise CRM, Sage CRM and other market leaders. By using the Cloud Elements CRM Hub s uniform API, you will be able to integrate your application once to the CRM Hub and instantly be integrated to all the prebuilt connectors (Elements) for the cloud CRM providers in that Hub - without changing your application s code. The following sections in this document guide you through the process of provisioning Elements within the CRM Hub (i.e. connect to the Cloud providers) using your customer s account credentials, as well as how to use the CRM Hub APIs in your application. Definitions Below are definitions of terms referred to throughout this document: Hub a uniform API to integrate an entire category of Elements (e.g., Documents, CRM, Customer Service). You integrate to a Hub. The APIs for a

3 3 Hub are available online at elements.com/elements/apidocs/ Element - Cloud Elements software code that provides a prebuilt integration into a specific cloud service vendor that enables a connection to an application, database, or service. You license Elements. You provision Elements by credentialing them into a Customer Account. Customer Account(s) - Your Customers connect a specific account of a cloud application or service to an Element by entering their unique account credentials for the cloud application or service they want to use in conjunction with your application. If your application is a B2B application then these are typically administrator account credentials. If it s a B2C application then these are typically individual user credentials. Note: Customer Account is sometimes referenced as Instance or Customer Account Instance within this document and on the User Interface and API calls. Developer Account(s) - Your Developers integrate Hubs into your application using our API or the Elements Manager console. Use as many developer accounts as you want; they re free! Sign Up for an Cloud Elements Account Before you can provision your first Customer Account for a CRM Hub Element, you will need to sign up for the Cloud Elements service located at: elements.com/elements/jsp/login.jsp. To ensure security, the signup and activation process must be completed using the website. An activation key will be sent to the provided address, which implicitly also verifies your account. The signup process is very straightforward, and you can alternatively use your Github account via OAuth to signup. Using your Github account also allows you to conveniently push sample API usage code directly into your Github repository.

4 4 Provisioning Customer Accounts for an Element Customer Accounts are associated to a given Element via a provisioning process accomplished either via the Elements Manager web application or directly within your app via RESTful APIs. For the CRM Hub Elements, the Customer Account information is typically your Customers account information for the service associated with the Element (e.g. Salesforce.com Element is provisioned with your Customer s Salesforce.com login account information). Provisioning a Customer Account for an Element via the Elements Manager To provision Customer Accounts for an Element using the Elements Manager web application, sign in to your account via elements.com After signing in, you are now ready to provision a Customer Account for an Element within the CRM Hub. Click on the Elements Catalog link in the left navigation bar.

5 5 Click the Add Element button for the required Cloud provider for which you want to provision the Customer Account. In this example, we will show how the Salesforce.com Element is provisioned for a given Customer s Salesforce.com Account in the example below.

6 6 When creating a new CRM Element Customer Account, you will need to provide the authentication and other details in order for the Element to verify and connect to the provided Customers Account credential information. Select the Setup using your Salesforce.com Account button as shown below, enter your Salesforce.com login information, and then click Next. You can ignore the Interactions sections for now (future functionality that is coming soon!).

7 7 You have the ability to optionally add tags to the Customer Account. Tagging is a powerful facility to enable you to track and monitor unique Customer Accounts for each Element: 1. You can assign any combination of tags per Customer Account Tag by environment such as development, test or production Tag by application such as social or billing Tag by anything else you want to track such as division, region or other. 2. Tags can be used to Track and monitor a single account used across multiple Customer Accounts (e.g., different environments or applications) Make it easier to keep track of what accounts are being used for (e.g., prod, test, your new social media app) 3. Analytics, monitoring and logging can all be filtered by Tags You can filter analytics by any combination of Tags and Elements

8 8 Select the Done button and then the My Elements button in the left navigation bar. You will see your newly provisioned Customer Account for the Salesfore.com Element, including the API documentation and sample integration code. In addition, upon selecting the Token button, you will see the element token for your Salesforce.com Element s Customer Account. This token will be passed on the header of each Salesforce.com Element API request from your application. Please keep this token secure, as unauthorized access to the Element Token could compromise your security. This completes the steps for provisioning Customer Accounts for the Salesforce.com Element using the web GUI. If you wish to provision another Customer Account, or provision a different type of CRM Element, just follow the steps again.

9 9 Provision a Customer Account for an Element via the API The following sections illustrate how to provision Customer Accounts for the Salesforce.com Element using the provisioning API. The base URL for all Cloud Elements APIs is: Each of the APIs in subsequent sections is then appended to this base URL. For example, to get the OAuth URL, use: Your Cloud Elements Organization and User secrets are required to use the provisioning API. To obtain these, sign in to the Elements Manager and edit your profile. At the bottom of the profile screen, the Organization and User secrets are listed: Note: If one is not there, click the Reset button to generate a new one for you. Provision the Customer Account Once you have all of the authorization information you need, you call the createinstance API, and it will create the Salesforce.com Customer Account in the Cloud Elements database. For detailed documentation about required v/s optional values, please go to elements.com/elements/apidocs/#!/provisioning/_post_14. In the properties below, use the same values, as you would enter in the GUI above. Method Header Body Input POST /provisioning/createinstance Authorization: User <user secret>, Organization <organization secret> "account": "key": <user s registered address> "instance": "tags": [ "name": <tag name> ], "element":

10 10 "key": <element key e.g. sfdc, sugarcrm> "name": "<Unique name for the instance>", "properties": [ key: "sfdc.username" propertyvalue: "<SF Username>" key: "sfdc.security.token" propertyvalue: "<SF Security Token>" key: "sfdc.password" propertyvalue: "<SF Password>" key: "sfdc.api.key" propertyvalue: "<SF API Key>" key: "sfdc.api.secret" propertyvalue: "<SF API Secret>" key: "sfdc.token.url" propertyvalue: "<SF Token URL>" key: "sfdc.revoke.url" propertyvalue: "<SF Revoke URL>" ] Return "datareturned": true, "token": <element instance token>, "name": <instance name>, "success": true For example (the data below is for example only: you'll have to use real data on an actual call): POST "account": "key": "[email protected]" "instance": "tags": [

11 11 "name": "My Tag" ], "element": "key": "sfdc" "name": "SFDC Instance", "properties": [ key: "sfdc.username" propertyvalue: "[email protected]" key: "sfdc.security.token" propertyvalue: "0dC0NoEFmAF8SbKcRXxNVAUyY" key: "sfdc.password" propertyvalue: "mypassword01" key: "sfdc.api.key" propertyvalue: "3ZYXWXYZ.DEFGhijk <etc>" key: "sfdc.api.secret" propertyvalue: " " key: "sfdc.token.url" propertyvalue: " key: "sfdc.revoke.url" propertyvalue: " ] with an additional request header Authorization: User 12345abcde12345abcde12345abcde12, Organization 12345abcde12345abcde12345abcde12 The result would be: "datareturned": true, "token": "ab123abcdef123456abcdef123456abc", "name": "SFDC Instance", "success": true

12 12 The returned token value is the Element authorization token, which will be used for all API invocations for your Customer Account associated with the Salesforce.com Element. This step completes the Element Customer Account provisioning process. At this point, your Customer Account is now ready to use. Use your provisioned Customer Account With the Customer Account token returned above, any of the CRM Hub methods can now be invoked. For example, use the following API to retrieve a listing of accounts in the CRM system. Method Header Query Input POST Body Return GET /document/list Authorization: Element <element instance token> FindAccounts "isaddactivityhistory": "(boolean)", "sortby": [ "field": "fieldname (string)", "order": "asc desc (string)" ], "isaddopenactivity": "(boolean)", "filters": [ "field": "fieldname (string)", "datatype": "datatype (string)", "useor": "(boolean)", "fieldvalue": "fieldvalue (string)", "closeparen": "(boolean)", "openparen": "(boolean)", "operator": "operator (string)" ] "datareturned": true, "accounts": "recordcount": /* number of records */, "records": [ /* record data goes here */ ] "success": true To continue our example, we would call: GET

13 13 with an additional request header Authorization: Element 12345abcde12345abcde12345abcde12 and post body of: "isaddactivityhistory": "false", "sortby": [ "field": "name", "order": "asc" ], "isaddopenactivity": "false", "filters": [ "field": "name", "datatype": "string", "useor": "false", "fieldvalue": "TestAccount", "closeparen": "false", "openparen": "false", "operator": "equalto" ] The result would depend on what's in the root directory, but might look something like the following. In this case it returns a single account with the name Test Account. "datareturned": true, "accounts": "recordcount": 1, "records": [ "SicDesc": null, "UpsellOpportunity c": null, "AccountSource": null, "phone": null, "TickerSymbol": null, "SLAExpirationDate c": null, "OwnerId": "005i VNdeAAG", "LastModifiedDate": " T16:20: ", "type": null, "BillingLatitude": null, "AnnualRevenue": null, "LastActivityDate": null, "id": "001i000000PzBddAAF", "NumberOfEmployees": null, "NumberofLocations c": null, "parentid": null,

14 14 "SystemModstamp": " T16:20: ", "SLASerialNumber c": null, "name": "TestAccount", "websiteurl": null, "industry": null, "shippingaddress": "street1": null, "postalcode": null, "stateorprovince": null, "city": null, "country": null "ShippingLatitude": null, "BillingLongitude": null, "Description": null, "sic": null, "Jigsaw": null, "LastReferencedDate": " T16:20: ", "Site": null, "fax": null, "LastModifiedById": "005i VNdeAAG", "SLA c": null, "number": null, "Active c": null, "CustomerPriority c": null, "deleted": false, "MasterRecordId": null, "LastViewedDate": " T16:20: ", "ShippingLongitude": null, "Rating": null, "CreatedById": "005i VNdeAAG", "CreatedDate": " T16:20: ", "JigsawCompanyId": null, "billingaddress": "street1": null, "postalcode": null, "stateorprovince": null, "city": null, "country": null "Ownership": null ] "success": true For testable API usage documentation for all the CRM Hub APIs, please refer to the online documentation located at: elements.com/elements/apidocs/ -!/crm

15 15 Online Documentation For testable API usage documentation for all the CRM Hub APIs, please refer to the online documentation located at: elements.com/elements/apidocs/ -!/crm In addition, testable API documentation where the HTTP header is pre- populated is available via the Elements Manager. To access this documentation, sign in to Elements Manager, and select My Elements from the left navigation bar, then select the Payments tab to view your provisioned Customer Accounts. Get More Support For assistance from our support team to help you with your applications, please visit or us at elements.com.