Customer activation process
To be able to use a Marketplace service, clients must activate it.
The providers’ services are accessed via the “Marketplace” menu item in onOffice enterprise or via the action bar in the individual modules such as real estate and addresses. All providers are listed in a pop-up in the “Overview” menu item. The menu items below list the providers and their services individually.
If the user selects a provider that has not yet been activated, a pop-up for activation opens. Activation is only possible as an administrator.
This short video shows the entire activation process. Click on the image on the left to start the video.
In the first step of activation, the user confirms your General Terms and Conditions (GTC) and the Data Processing Agreement (DPA). The following screen is then displayed:
- “To provider” shows a description of your company and your services. The rights that the user must grant you are described under “Description of the rights to be granted” . This means that the user is aware of which data is being accessed.
- Under “Activate user right” , the user must consciously set either “For all users” or “For all administrators” so that the activation can be carried out. Administrators always have access. For Marketplace providers who offer exactly ONE service via webhook, this selection is deactivated and “for all users” is preselected. The API key is displayed directly in this case.
- After setting the user rights, the API key appears. This must be copied manually into the second API key field in your iFrame. The customer thus allows your service to read and write via the API user in the customer version. You must save the API key for each customer.
Attention: The second API key field is an iframe from the Marketplace provider. This means that you program this part of the activation pop-up yourself. It is best to program the activation first and then the actual store. Please let us know the URL for activation as soon as possible. This ensures that you can test your store implementation directly.
In the code examples you will find a program code as a template for the design. You can customize it, for example to change the appearance or display specific information or error messages for your service. Please use this HTML framework to display your iframe.
The iframe URL must be publicly accessible for integration. As long as you have not provided us with the URL of the iframe, the following error message will be displayed: “Activation of the provider is currently not possible. Incorrect URL for activating the API user.”
Open Sans font: Would you like to use the Google font “Open Sans” from our servers? To do this, include the following line in the header of an HTML file:
and adapt your CSS file as follows to use the font:
font-family: ‘onOffice Open_Sans’
Activation requires the following steps:
- Confirm GTC and order processing agreement
- Select user right
- Copy API key
- Insert API key into your iframe
- Take note of the privacy policy
- Click on “Activate now” to activate the provider.
Structure of the iframe URL for activation
When the activation URL is called up in the iframe, customer identification data is transmitted:
- API token: apiToken
- Name of the customer: customerName. A customer is an instance of the onOffice software that can have many users. customers are often brokerage firms and users are the brokers.
- WebID of the customer: customerWebId
- UserID of the user: userId. The userId together with the customerWebId uniquely identifies a customer. The userId alone is not enough.
- Parameter cache ID: parameterCacheId
- Timestamp: timestamp
- Signature: signature
Timestamp
To ensure that the iframe is called via onOffice enterprise , the following procedure is used:
- A timestamp parameter is added to each URL generated by onOffice to call a service frame (…timestamp=123456789). The timestamp ensures that the links cannot be used as often as required.
Signature
In addition, all calls to a URL are signed by onOffice according to the following procedure:
- A signature is generated over the complete URL using the hash_hmac function.
- An additional part of this signature is a secret, which you must set once when you join the Marketplace. You can enter and change the secret in your provider customer in the menu Marketplace >> Change provider secret. The secret is valid immediately after saving. Therefore, make sure you can process it immediately. Frequent secret changes are not advisable; the secret is also used, for example, in the link for recalculations that your customers receive by e-mail. The secret must consist of at least 24 characters and contain upper and lower case letters, numbers and special characters.
- The generated hash is again appended to the URL as a parameter.
For the signature, the URL including all parameters (except the signature parameter) is encrypted using hash_hmac, sha256 (see checkSignature in the code examples). The parameters are sorted alphabetically. The validity of the signature can be checked via the time stamp.
Activation of the provider
To ensure that your service can read and write data in the customer versions, an API user is automatically created in each customer version when your service is activated. The API key and the token for authentication are given to you during activation.
You authenticate yourself with the API key entered and the token provided. You must call the API function for unlocking the provider (ACTION_ID_DO, ‘unlockProvider’) and pass the parameter parameterCacheId to it (see unlockProvider.js in the code examples). The parameter parameterCacheId contains internal information that was saved in the parameter cache.
If successful, your offer is now activated. Save the API access data (API key and token) for each customer. A customer can be uniquely identified via the combination of customer ID (customerWebId) and user ID (userId). As feedback for the user, you must report the result back to the popup via JavaScript .
If successful, “active” should be returned to the user; if an error occurs, an error message should be returned. (see unlockProvider.js in the code examples).
The status changes from “Inactive” to “Active”if successful .
The API key is the secret of your API user at the customer. The customer who wants to use your services copies the API key into their iFrame during activation, thereby transmitting it to you and giving you rights to access their onOffice software. Therefore, please save the API key and the token for each customer. Many services in the Marketplace require read or write access to certain resources in onOffice enterprise in order to function. Example floor plan optimization: Customer orders floor plan in the Marketplace for a specific property (provider must have read access to property or floor plan), provider creates floor plan, provider plays back optimized floor plan (provider must have write access to property).
Please note: You do not need to create your own API users for your service. The API users for your service in the customer versions are created automatically when the customers activate your service. The necessary information (API key and token) is transferred. The customer actively copies the API key into your iframe and the token is transferred when the activation URL is called up in the iframe.
Please notethat an “extendedclaim” parameter must also be specified for each API call. A parameter “apiClaim” is therefore transferred to you each time your service is called by the customer. You must then return this “apiClaim” as the “extendedclaim” parameter for all API calls. This ensures that the transfer of the user ID and the customer version is verified. Please use the “apiClaim” from the customer’s latest service call. The apiClaim during unlocking can only be used for the unlockProvider call.
More detailed information on this can be found at https://www.marketplacedoc.onoffice.de/api-calls.
The user has activated your offer. Your services can now be booked via the “Marketplace” menu item in onOffice enterprise. When the user calls up your service, your iframe with the desired service front end is displayed in the pop-up.
This post is also available in: German