To successfully build an integration with Reviso you need to follow a couple of steps. This post tries to explain step by step how to get up and running. It contains explanations about the following topics which must be completed to get access:
- signup for developer agreement
- create an app definition
- enable the app (generating a grant)
- use the rest api
Signing up for a Developer Agreement
To sign up for a developer agreement simply navigate to: https://www.reviso.com/developer and fill out the form under developer signup to the left.
This will generate a developer agreement for you. This agreement will be marked as being a trial and will only last for a specific number of days. To change this please write to firstname.lastname@example.org informing us the number of the agreement and the general purpose of the integration, and we can help to extend this period or make it permanent.
Creating an App Definition
The developer agreement can contain any number of app definitions. When you sign up we create one for you, but if it does not fit the purpose of what you need you can just delete it and create a new one.
To create an app definition simply use the ui provided when you log into the developer agreement.
An app definition has a number of properties that help you connect your app to reviso, and the instructs reviso how to treat the app.
This is the name of the app, which is used to present it to reviso’s customers when they are enabling the app and if the decide to remove it again later.
This is the unique identifier that can be used to identify the app when asking users to enable the app (more on this later), and when contacting reviso (ie. for support).
This can be re-generated if you would like to re-release the app, but please notice that all links to register for usage of the app will no longer work.
This private token should not be shared with anyone, as keeping it secret is integral to the security model.
This can be re-generated (for example if the private token has been exposed to the public), but be aware that this means that all existing grants generated for the app will stop working
The list of roles describe the different data the app can access in Reviso. Not all users in Reviso can access all data, so only add the roles that is required for your app to work. For instance, unless your app specifically touch upon those areas the roles inventory, project analysis, project employee and reporting are probably best left out.
If a user does not have access to a given role (usually indicated by a module as can be subscribed to inside reviso), he will not be able to enable the app, and similarly if he has enabled the app and a required module is removed then the app will no longer be able to access that data.
Enabling an App
In Reviso there are at least two agreements involved when getting access to the api.
- developer agreement, containing the app(s) definition
- business agreement(s), containing the accounting data, such as accounts, customers etc.
To enable an app to get access to a specific business agreement’s data, a grant must be generated. A grant represents one apps access to a specific business agreement’s data (on behalf of a specific user in that agreement), and if deleted the app will no longer have access to the data (unless another grant exists).
To enable an a app the user in the business agreement needs to navigate to https://app.reviso.com/api1/requestaccess.aspx?appPublicToken=publicToken where the last publicToken bit is the public token as described previously.
The user will be presented with information about the app and what data it needs access to. If the user wishes to enable the app he will simply have to confirm by entering agreement, user id and password.
The page will then return a grant token which must be passed on to the app.
To retrieve data from the api you will need two tokens:
- private app token (as described above)
- grant token (as generated previously)
These can be used to access data as described in: http://api-docs.reviso.com/