Listing a partner integration

OfficeRnD has a plethora of integrations that serve various purposes, however if there's a platform that we've not yet integrated with, this process can be used in order to create a partner integration with OfficeRnD.

📘

Note

In order for your integration to be listed as a partner integration in OfficeRnD you must first complete our approval process, please find more information here.

Once you've completed the approval process you can complete the steps in this article in order to connect your integration with OfficeRnD.

Creating a developer application

The first step to creating a partner integration is by creating a developer application in the OfficeRnD admin portal.

During the creation process you'll be able to specify basic information about the integration.

After the application is created in OfficeRnD the next step would be to send us additional details about the integration that are needed to complete its setup - more on that in the next section.

❗️

Important

Integrating with OfficeRnD is based on the OAuth 2.0 authorisation code flow.

We've prepared an example nodeJS application that will allow you to see how all URLs should look like. You can use that to build your own application.

Requirements you need to send to us

After you've created the developer application there's a couple of more things that you need to send to us at OfficeRnD in order to finalise the creation of the partner integration:

📘

Note

All of the information that is required can be sent to us through the partner program process.

• Connect URL - this is the URL to which the user will be re-directed when they try to establish a connection between OfficeRnD and your platform by using the "Connect" button in OfficeRnD.
  Please note that this URL will be opened as a pop-up in the admin's browser when they try to connect the integration. In other words this URL can open a UI that will allow the user to connect to your platform.
  This request should capture the 4 parameters that will be sent from ORND.

• Configuration URL - this is the URL, that will be used to open the configuration settings of the integration.
  This configuration could contain various settings related to the integration

• Healthcheck URL - this is the URL that is used to check if the integration is successfully connected.
  The healthcheck URL should return one of the two following values:

  • If the connection is successful - the URL should return the name of the account in the connected platform, i.e the response should look like so:
    
    

    
      { "accountName": "_J&J Ltd" }
    
    

    Example: If the account which the user is trying to connect is called J&J Ltd in your platform, then that's the value the URL should return, if the the connection is successful.
    
    
  • If the connection is unsuccessful - the URL should return an error with additional info about the problem that has occurred. More specifically it should include some sort of error code and and the response should look like so:
    
    

    
     { "message": "the message goes here" }
    
    

• Sync URL (if applicable) - this is the URL that will  be used to toggle a sync between your platform and OfficeRnD. Depending on the type of integration you're building.

• Multi Location Support - one of the things that we'll need to know is if a customer can connect multiple accounts to a single OfficeRnD account. 
  In OfficeRnD we have locations and some integrations allow each location to have its own integration in order to make it easier to distinguish between data from one location to another.

📘

Note

All requests that are made to the connect, configuration, healthcheck and sync URLs are of type GET.

Configuring the Healthcheck, Configuration and Sync URLs

For all 3 of the requests the following query parameters can be used:

• slug - this stands for the organisation slug, see here how you can procure it.
• locations - this stands for the id of the location. You can get a list of all locations and their names by using our API and calling this endpoint.
• signature - here you can use the "secret" from this step.

Setting up the integration

There are several steps needed in order to complete the setup of the integration:

• Step 1 - information that you'll receive when a user tries to Connect the integration
• Step 2 - generating an access token in order to authenticate your integration to OfficeRnD
• Step 3 - retrieving secret used to sign requests from OfficeRnD to your integration
• Step 4 - Verifying payloads from OfficeRnD
• Step 5 - Subscribing to our webhooks
• Step 6 - Set up a return URL

📘

Note

All of the steps below are a result of OfficeRnD calling your ConnectURL.

Step 1 - information that you'll receive when a user tries to Connect the integration

After the integration is added to the admin UI and a user clicks the "Connect" button you'll receive the following query parameters

• code - this code is extremely important as it can be used to be exchanged for an access token in order to authenticate to our API.
• org_slug- the slug of the organisation for which the integration will be built. If you're doing testing you can use your test organisation's slug by going to "Settings"->"My Account" - the slug can be taken either from the "Admin Site" field.
• locations- the ids of the locations for which the integration will be connected
• integrationId - the id of the integration, that you created.

Step 2 - Generating an access token in order to authenticate your integration to OfficeRnD

In accordance with the OAuth 2.0 protocol, an integration needs to obtain both an access token and a refresh token. The access token is valid for 1 hour, while the refresh token remains valid for 15 days. These tokens allow secure, temporary access to the API, with the refresh token enabling the generation of a new access token when needed.

All parameters mentioned above are required in order to authenticate to our API and generate an access token.

The URL that you need to call in order to generate the tokens is:

curl --location --request POST 'https://identity.officernd.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=client_id' \
--data-urlencode 'client_secret=client_secret' \
--data-urlencode 'code=code' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_url=https://url.com/connect/return' \
--data-urlencode 'scope=officernd.api.write officernd.api.read'

📘

Note

For scope you can specify whether you'd like the token to have permissions to read, write or both, concatenated into a single string divided by a blank space e.g. "officernd.api.read officernd.api.write.
If you specify scope that your application doesn't have you'll encounter an error.

Step 3 - Retrieving secret used to sign requests from OfficeRnD to your integration

Once your integration is live, it'll be open for any requests sent to it. For security reasons, you should verify all incoming requests and allow only those coming from OfficeRnD. All requests sent by OfficeRnD are signed and the signature is included in the signature query parameter. Using the integration's secret and the request query parameters you should verify the computed signature matches that in the query.

Before you can verify signatures, you need to retrieve your integration secret.

Secrets are unique for each integration. If there are multiple instances of your integration, you will need to verify the signatures for each with their respective secret.

After the token from the previous step is generated you'll be able to retrieve your secret using the following request:

curl --location --request GET '<https://app.officernd.com/api/v1/organizations/{{org-slug}}/integrations/{{integrationId}}?appClientId={{client-id}}'

You'll need the following for the request above:

• Both the org-slug and integrationId will be provided from our end.
• client-id - this can be procured by going to the admins portal and going to "Settings"->"Developer Tools" and clicking "View". Here you'll find the "Client Id", which you can use in order to complete the request above. 

🚧

Warning

The client secret that is visible after you click View in Developer Tools is different from the "secret" used to sign requests that is procured by completing this request.

After the request is complete you should be able to get your "secret" - make sure you store it and keep it somewhere safe:

Step 4 - Verifying payloads from OfficeRnD

OfficeRnD creates a hash signature with the query parameters of each request. The signature is included as a query parameter called signature. For extra security, in addition to the signature, each header contains a timestamp (prefixed by t=) which is used in the hash computation.

Examples of payloads OfficeRnD will sign:

  '{"slug":"test-slug","locations":"location-id1, location-id2"}.1648190384' - multi-location integration
  '{"slug":"test-slug","locations":""}.1648190384' - all locations integration

The signature has two fields, separated with "," - t and signature.

It will will look similar to this:

   
  t=1602237976,signature=099618786b221c0bd88346a71e01c8deec60007c2db2ead5975284d4e957b8f5

Signatures are computed using an HMAC hex digest with SHA-256. The request query parameters and timestamp are joined by a dot . and HMAC hashed. In order to verify the signature, you will have to repeat the process with the incoming data and compare your result to the signature in the query.

1. Extract the timestamp and signatures

• Split the header using a "," as the separator.
• Then split the resulting elements (t=.... and signature=...) using the "=" character as the separator.
  This will give you two pairs to work with - the timestamp and its value, and the signature and its hash.
• Verify the timestamp and the current timestamp difference is within your tolerance

2. Prepare the payload to sign. Concatenate the pieces in the following order:

• The JSON containing the query parameters which is then stringified (Example - verifySignature in the example application)
• The dot character "."
• The timestamp value

3. Compute the expected signature

• Compute an HMAC with the SHA-256 hash function
• Use the integration secret as the key
• Use the concatenated string from step 2 as the message

4. Compare the signatures

• Compare the header signature from step 1 to the expected signature from step 3

Step 5 - Subscribing to our webhooks

In order to make it possible to disconnect the integration on the user end you can subscribe to our "Integration.removed" webhook - more on webhooks here.

Step 6 - Set up a return URL

After all of the other steps are completed there must also be a return URL that is set up, please find it below:

  https://app.officernd.com/connect/external-integration/return

This will make sure that after the whole flow is completed the client is redirected to OfficeRnD.

Exposing the integration for other customers

After the process of configuring the partner integration is completed, the integration will be visible only for your test account in OfficeRnD.

In order to expose it for other OfficeRnD customers you'll need to contact OfficeRnD at [email protected] in order for us to make the integration available to other customers.

This should be done after you've finished testing the integration and you're confident that it's ready to go live.