Documenting Integration Requirements
Top 20 Questions For Thoughtful Integration Documentation
More and more, our clients want to integrate Salesforce CRM or their Conga Contracts applications (their "Solution") to a database or business application. The question they almost always want to know is "how much will it cost?". To answer this question, first be prepared to present a high-level description of your integration. This could be a paragraph or a number of bullet points that summarize what the integration needs to do. However, to reasonably answer the cost question, we typically need documented requirements. The following article reviews basic questions you should be prepared to answer and document.
Documented requirements can be produced by you - the client, or you can hire a firm like akaCRM for a short "phase 1" engagement to facilitate the discovery and documentation of your requirements. If you elect the latter, you own the deliverable document under which you can (a) hire the documenting firm to implement, (b) bid them to other firms, (c) do the integration yourself or (d) put the project on the shelf for a later day. If you prefer to document the requirements yourself or are preparing for your integration discovery meeting with us, the following are some of the initial questions that we like to document in order to make a recommendation on approach, technology and the associated cost and timetable.
- What are the databases (or business applications) that you want to integrate? We will often refer to each end of an integration connection as an "endpoint".
- If it is a database that your Solution is connecting to, what is the type and version of the database? E.g., MsSQL, MySQL, Oracle, MS Access., etc. and what version.
- If it is a business application, what edition or version is it?
- Does the database or application have an API (application programming interface) or web-services? If yes - attach any documentation you have on the API or web-services.
- What edition of your Salesforce or Conga Solution do you have? Does your edition have the API? Salesforce Enterprise, Unlimited, Platform and Developer Editions provide the API and additional coding tools; Professional Edition will in very limited cases be sufficient for custom integration. In nearly all cases, Essentials Edition will not support custom integrations. Consider upgrading in these circumstances if integration is a requirement.
- Does the database or application have Internet access (if not a web-based application)? Since Salesforce and Conga are web-based applications, in order to integrate, you will ultimately need to provide some mechanism to get the data from your database or application to the Internet.
- What do you want the integration to do? This one is critically important and in many cases, you may want the integration code to do lots of things. For example, do you want a one-way integration where invoices from your financial system are pushed to a custom object or table in Salesforce or Conga and updated or are you looking for a two-way sync where accounts, opportunity, products and invoices stay in sync. Consider drawing it out on paper with one way or two way arrows. Include the diagram in your documented requirements.
- What do you want to be the trigger to move a record or cause the integration to begin? For example, is it the creation of a record, a change to the record, or a batch process that runs every night.
- If the integration can be triggered by a person, what roles or profiles or people will be allowed to kick-off the process?
- If the integration is a batch process (a group of records updating the other system periodically), specifically what records are included in the data set - all of the records or only records meeting certain filtered criteria? How frequently would the batch run and is there a particular time of the day and/or week it should run?
- Also, if the process is a batch process, how many records are likely to be included in the typical data set and how large could the data set become? For example, are you pushing the entire data set daily or just adds, edits and deletes? Are the number of records likely to be in the hundreds, thousands, tens of thousands or millions? What about in one year or three years? We want to build in scalability so that it keeps working for years to come. This count will also help us recommend the correct technology. For example if your record set is very large it could take days to process the entire data set with one technology and hours with another.
- Do you need the integration in real time or near real time, or is a weekly or monthly update adequate?
- What happens if the integration fails or if one of the end-points is offline? Does it need to be reprocessed or can the data set be skipped?
- When the integration runs, what type of error logging if any do you require? What happens if the integration encounters unanticipated results? E.g., no record match, duplicate record match or out of bounds values?
- How many endpoint pairs will there initially be as part of your integration? (e.g., SQL<>Your Solution would be 1 pair).
- Do you expect the number of endpoint pairs to grow over the next 24 months?
- How frequently will the integration code need to be updated? E.g., will you be adding new fields or logic over the next year that will require changes to the integration?
- Do you already own an integration middleware? Examples include Mulesoft, Dell Boomi, IBM Cast Iron, Informatica, Jitterbit, Pervasive, Scribe, Dataloader.io plus many application specific connectors.
- Do you have internal developers that will be maintaining the integration code or supporting the middleware? If so, are there preferred technologies?
- What is the ROI for the integration? To figure this out, estimate the amount of time saved by individuals that would have to double enter data, correct duplicate data or would have to search for data. Estimate their hourly rate. Solve for the equation: Annual Cost Savings = (hours of effort saved each month x avg hourly rate of impacted employees x 12 months) - less the upfront cost of the integration development (one-time fee) + any middleware licensing costs (typically an annual fee). If your number is negative, consider not doing the integration unless there are subjective factors like the cost of customer satisfaction that is impacted. If the number is positive, consider how many months it will take to recover the initial investment (aka your payback period). You may also want to spread the upfront integration development over multiple years.