Activation process for the customer
The services of providers can be accessed via the menu item “Marketplace” in onOffice enterprise. In the menu item “Overview” all providers are listed in a popup. The menu items below list the providers and their services individually.
If the user selects a provider that has not been activated yet, a popup opens for activation. Activation is only possible as administrator.
In this short video the whole activation process is shown. 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 Order Processing Agreement (OPA). The following screen is then displayed:
- “To Provider” shows a description of your company and services. Under “Description of the rights to be released” the rights that the user has to allow you are described. This means that the user is aware of which data will be accessed.
- Under “Activate user rights” 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.
- After setting the user rights, the API key appears. This must be copied manually into the second API key field.
Activation requires following steps:
- Confirm GTC and OPA
- Select user right
- Copy API key
- Insert API key into your iframe
- Take note of the data protection provision
- With a click on “Activate now” the provider is activated.
Setup of the iframe URL for activation
When the activation URL is called up in the iframe, data for identifying the customer is transferred:
- Name of the client
- WebID of the client
- UserID of the user
- Time stamp
To ensure that the access to the iframe is done 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=1234569). The timestamp ensures that the links cannot be used as often as desired.
In addition, all calls to a URL are signed by onOffice according to the following procedure:
- A signature is generated over the complete URL with the function hash_hmac.
- An additional part of this signature is a secret, which must be set once by you when you add it to the marketplace. In your provider client, you can enter the secret in the menu Marketplace >> Change Provider Secret and also change it. The secret is directly valid after saving. Therefore, make sure that you can process it immediately. We do not recommend frequent changes to the secret, as the secret is also used, for example, in the link for backbilling 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 parameter signature) is encrypted using hash_hmac, sha256 (see checkSignature in the code examples). The parameters are sorted alphabetically. You can use the timestamp to check the validity of the signature.
Activation process for the provider
They authenticate themselves with the entered API key and the transferred token. 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 parameter contains internal information that was stored in the parameter cache.
In case of success “active” should be returned, in case of error an error message should be returned for the user. (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 site. The customer, who wants to use your services, copies the API key into their iFrame during the activation process, thereby transferring 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).
The user has activated your offer. Your services can now be booked via the menu item “Marketplace” in onOffice enterprise. If the user calls your service, your iframe with the desired service frontend is displayed in the popup.
This post is also available in: German