Partner integration

Building an integration as a partner is mostly the same as building an application integration.

However, as opposed to application integrations, partner integrations are not built for a specific account but rather as a generic integration solution between the partner’s system and Oneflow. As such, they can be used by anyone in Oneflow, not just a single customer. The general nature of partner integration requires making only minor changes compared to the application integration workflow.

As a partner, to build your integration, you can follow the standard procedures of authenticating, creating contracts, using webhooks, etc., described in this documentation. You can build and test almost the entire integration workflow using the Oneflow integration platform’s components without any involvement from the Oneflow team. You will temporarily need to hardcode some things, like template type IDs and webhooks. While doing this makes the integration easy to build, it will limit it to a single Oneflow account.

See this section to learn how to get started with building a Oneflow integration.

To make the integration general so that any customer in any account can use it, you need a Oneflow integration extension. Oneflow builds this extension in collaboration with you.

Integration extension in Oneflow

When you’re satisfied with the integration and have ensured that everything works as it should, you’re ready to take the final step and make the integration ready for use by end customers.

At this step, Oneflow will build an integration extension in the Oneflow system. While it is possible to build a generic integration without a Oneflow integration extension, the extension provides tangible benefits:

• Your integration extension is listed on the extension page in Oneflow.
• Customers can enable the extension (from the Oneflow side) with a single click.
• Enabling the integration extension will make the Oneflow system automatically create an API token and display it to the user.
• Any template types and webhooks required by the integration are also created automatically.
• The automatically created webhooks are preconfigured so that the system will send events only for those contracts that have been created via the extension (see Template types and webhooks chapter that follows.)
• Ability to filter templates based on template types that work for partner integrations (see the Getting workspaces and templates chapter below.)
• Prevents users from accidentally deleting any API tokens, template types, or webhooks needed for the integration.

Template types and webhooks

For each template type created by an integration extension, Oneflow will create a corresponding webhook. The events sent out via these webhooks can be filtered.

The webhook will only send out events in the following cases:

• The user created a contract from a template with a template type connected to the webhook.
• The user created a contract via the integration extension (contracts created directly in Oneflow are not included).

Additionally, integration extensions allow for additional parameters and authentication for webhooks. For example, if your receiving endpoint requires authentication via OAuth, a customer, or an account ID from your system to handle the incoming contract events.

Getting workspaces and templates

While hardcoding workspace and template work well for some integrations, it rarely, if ever, works for partner integrations. Instead, the user should be able to select amongst the workspaces they have access to and the templates available for that integration. To help with this filtering, Oneflow provides a helper endpoint to get data for creating a contract.

To get familiar with this endpoint, see the Get data to create a contract tutorial.

🚧

Note:

It is impossible to filter a template type created by an integration extension using the template type ID since the template type gets created from a blueprint. Each account that enables the integration extension gets its copy with a unique ID. Since the template type ID is different for each account, we cannot use it as a general means to filter by.

For this reason, template types created by an integration extension are assigned an extension type. This type is assigned by Oneflow when the integration extension is created. Use the extension type instead of the ID when filtering template types.

The 'Get templates' endpoint is another alternative method for retrieving available templates for the user, including workspace details. For more information, refer to the Get templates. Templates can be filtered by either template type ID or extension type.

📘

Note:

To list all extensions available for your account and identify whether an available extension type is in an enabled or a disabled state, please use the Get integration extensions endpoint.

Working with data fields

Template types created by an integration extension will automatically have some data fields. Which data fields, their names, descriptions, etc., you decide as a partner.

You can add, update and delete data fields from the template types you have manually created during the development phase.

As the development nears completion, you notify us of which template type with its list of data fields to use as the basis for your integration extension blueprint.

When a user enables the integration extension, it will automatically create the template types with their data fields, as defined by the blueprint.

📘

Note:

Any data fields created this way will be system data fields (source=system). Unlike the user data fields, you cannot modify the system data fields in any way other than changing the active flag. Setting a data field to active=false will make it act as a removed data field.

🚧

Warning:

Changing the flag during the contract creation will cause an error.

📘

Note:

It is possible to mix _user and _system data fields in the same template type.