From this starting point, you can navigate to the information and instructions you’ll need to complete the integration of your services with the PerfectLO Document Aggregation Service (DAS). We continue to improve our documentation and would like to hear from you about how to make it better. Once you let us know you’re interested, we’ll engage with you directly, so we can answer your questions quickly and offer additional guidance.
PerfectLO exposes a REST API to our partners. We’ve tried to stay true to the principles of REST and most of our resources have a direct correspondence to the objects that users will see in the UI of your application. These resources include things like documents (PDF, Word, text), document sources (Bank of America, Verizon), and document source “connections” which represent the persistent association between a user and their account on a website. Our API documentation describes each of these resources in detail.
There are two other points of integration between your service and ours: our change notification and document delivery services. In contrast to our API, where you call us, these two services make calls back to your service via webhook endpoints that you expose to us.
We suggest you proceed from here to our discussion of Tools that are useful for your development work, and then move on to the PerfectLO API documentation. When you’ve gotten a sense of how our API is structured, return here and we will explain how to set up your partner account.
A good way to become familiar with how your service connects to and communicates with the PerfectLO service, is to install our Partner Console application. The console is used to configure connections and to monitor logs during the operation of the system. It’s particularly valuable for correlating what you see in your logs with what you see in the console logs. The console is a desktop application and runs on Mac, Windows and Linux platforms. Once you’ve used it to set up your account you can explore how things like document deliveries work. The rest of this section will walk you through this.
First, contact us to obtain your partner account credentials. Then proceed the following instructions:
Change your temporary partner admin account credentials
Download and install the partner console
Log into the console
One PerfectLO subsystem that will require some work on your part is the service which manages the security questions that user websites pose as our fetching services visit their account websites to look for documents. These user interactions must propagate back to your system (via our change notification system) for your user to answer them in your application. The answers submitted by your users must then be returned to us (via a call to the PerfectLO API). When we receive the user’s answers, our fetchers can proceed with their work.
Some examples of user-interactions:
When PerfectLO needs to alert end-users to some condition, or when it needs to ask them a question, as sometimes arises during when fetching documents, it creates a user-interaction request. As a PerfectLO content delivery partner, or a client app writer, you are responsible for responding to these requests by posing the information or questions to users in your own user interface, obtaining their answer and returning their response to us so that we can complete the operation. An interaction may happen more-or-less synchronously, or may be completed over a period of hours, or even days. The two typical cases are:
Regardless of how long it takes to complete the user interaction, PerfectLO uses the same mechanisms to store pending requests, notify clients and partners that they need to be responded to, and completes the pending actions (i.e. fetch documents) once the responses are received.
When PerfectLO sends you a user-interaction request, it is not necessary to attach any meaning to what is being asked for or to write any special code to present requests to users. Instead, an interaction request is a self-contained description of what to present to the user and what responses are required. Given the interaction request, which is packaged as JSON, you just need to create and pose a UI form, let users enter information, and return their responses to us in another JSON record.
To illustrate how this works and to serve as a tutorial for writing your own implementation of the user-interaction workflow, we’ve written a sample application as a web app. Open this now to have a look. There are instructions in the client itself, but as a quick overview, here are descriptions of the purpose of each tab panel:
User Interactions Tab
This panel is a functioning implementation of the client side of the user-interaction workflow. It uses canned request data and does not interact with our API, but it parses sample request data, generates a live UI from it, accepts input from a user, and generates the response data that would be sent back when the user clicks the “OK” button in the form.
The variety of request samples will both give you an idea of the kinds of requests you’ll typically see from our servers and provides a range of different UI elements that you’ll be expected to render.
Source Code Tab
This panel shows copies of the actual JavaScript source code used by the previous panel. These are three code snippets that are central to making things work. Your implementation may not be in JavaScript, but you can use these as pseudocode for yours, knowing that they are complete and functional.
The first file, Request Parser, is generic JavaScript with no external dependencies. Given a user-interaction request, it will parse it and invoke abstract methods on a given “generator” instance. This parser is used in two contexts, each with different instances of concrete generator classes. The first use is to generate the GUI. The second is to extract the user-entered values from the GUI and generate the response data.
The second file, Form Generator, is an implementation of the abstract generator used by the request parser. The form generator creates GUI widgets. This generator is written to use the same Sencha ExtJS HTML 5 framework that the fake client itself is written for. It is therefore dependent on that framework’s classes. As pseudocode, though, you ought to be able to make sense of it and be able to map it to whatever UI kit you’re using.
The third file, Response Generator, is another implementation of the abstract generator. When a user clicks the “OK” button on the form, the fake client re-parses the request data using the parser instance but uses a response generator instead of a form generator instance. The response generator, which is also written to work with the ExtJS framework, knows how to extract user-entered values from the GUI widgets and it uses this to generate the required response JSON. Again, you can use this file as pseudocode to guide your own implementation using your UI framework.
JSON Schemas Tab
This panel shows the JSON Schema specifications for our user-interaction request and response data. Once your eyes adjust to the syntax, you can use this as a reference to understand what to expect.