Get Data To Create A Contract

Integration Toolkit > Get Data To Create A Contract

After implementing the authentication feature, your next goal is to create a contract. However, it is important to gather the relevant data before proceeding with contract creation.

Strcture - Getting started Oneflow integration — System Architecture

According to the system architecture, you will integrate with Oneflow and implement a custom integration within your system. When creating a contract through Oneflow’s Public API, you can include data retrieved from both Oneflow and your system.

This document outlines the essential information required for contract creation and explains how to obtain it. It is assumed that you have a basic understanding of the features of the Oneflow application and the endpoints available through the Oneflow Public API.

Important data to create a contract

Data	Description
Oneflow Workspace	Oneflow Public API allows the creation of contracts within a workspace. Therefore, `workspace_id` is a required parameter when creating a contract through the Oneflow Public APIs.
Oneflow Template	Oneflow Public API allows the creation of a contract based on a specific Oneflow template. So, `template_id` is a required parameter when creating a contract through the Oneflow Public APIs.
Contract Participants	Contract participants are another important aspect to consider when creating a contract. However, they are not a mandatory parameter for contract creation. By default, the person who creates the contract is automatically included as a participant on the contract owner's side.
Contract Data Fields	Contract Data fields are an important aspect that can be used as contract variables. However, they are not a mandatory parameter for contract creation.

How to get important data

Oneflow Workspaces

Your end users can create Oneflow workspaces only through the Oneflow application, as the functionality to create workspaces is not currently supported through the Oneflow Public API. However, when creating a contract, users should be able to select the workspace where the contract will be created. To facilitate this, you can provide a list of available workspaces for users to choose from.

List of workspaces available for the user

Here, you can create your own front-end components to allow users to select the workspace where the contract should be created. For example, you can implement a dropdown menu to enable users to select the relevant workspace easily.

Get Workspaces from Oneflow

You need to make an API call from your frontend to a backend endpoint in the Oneflow Integration within your system to retrieve the list of workspaces that a specific user has access to. The following function is designed to fetch all workspaces where a user has permission to create contracts, returning the data formatted as a JSON response.

FUNCTION GetWorkspaces
    INPUT: user
    OUTPUT: jsonResponse

    BEGIN
        # Initialize OneflowPublicAPI with authentication details
        validate request
        user = user  # get user's Oneflow Token and Email from authentication table in your DB

        TRY
            # Using the function GetPermittedWorkspaces to retrieve workspace data
            workspaces = Retrieve Permitted Workspaces for user using GetPermittedWorkspaces
        CATCH exception
            Handle the exception
            
        # Prepare the response data structure with workspace IDs and names
        Initialize workspaces_response with an empty list
        FOR EACH workspace IN workspaces
            # Create a dictionary for each workspace with ID and Name
            workspace_info = {ID: workspace.ID, Name: workspace.Name}
            ADD workspace_info TO workspaces_response

        # Convert the response data to JSON format and return it
        RETURN ConvertToJSON(workspaces_response)
    END

The Oneflow Public API allows retrieving a maximum of 100 workspaces at a time. Therefore, you must implement pagination to fetch all workspaces. Additionally, the user must have the “Create documents from templates” permission for their role in a particular workspace to create a contract using the Oneflow Public API.

Here is the function that fetches workspaces where the user has permission to create contracts. It uses pagination to retrieve and filter all relevant workspaces.

FUNCTION GetPermittedWorkspaces
    INPUT: user (includes API token and email)
    OUTPUT: List of Workspaces with Permission

    BEGIN
        Initialize permitted_workspaces as an empty list
        Initialize next_link as None
        
        LOOP FOREVER
            # Step 1: Fetch workspaces starting from the initial or next link
            selected_workspaces = Get Oneflow Workspaces using user and next_link using GetOneflowWorkspaces
            # Extract the list of actual workspaces from the 'data' field of selected_workspaces, which contains the workspace details
            selected_workspaces_data = Extract data from selected_workspaces
            
            # Step 2: Filter workspaces where 'contract:create' permission exists and is true
            Append to permitted_workspaces all workspaces from selected_workspaces_data where
                'contract:create' permission in '_permissions' is True
            
            # Step 3: Update next_link to point to the next set of workspaces, if available
            SET next_link to the next page link from selected_workspaces
            IF next_link IS None THEN
                BREAK the loop

        # Step 4: Return the list of workspaces with the required permissions
        RETURN permitted_workspaces
    END

Here’s an example function designed to fetch available workspaces for a particular user using the Oneflow Public API's Get Workspaces endpoint.

FUNCTION GetOneflowWorkspaces
    INPUT: user (includes API token and email), url
    OUTPUT: jsonResponse

    BEGIN
        IF url IS None THEN
            # Define offset and limit as strings
            DEFINE offset AS '0'
            DEFINE limit AS '100'
            # Define the API endpoint with offset and limit
            API_ENDPOINT = "Construct URL 'https://api.oneflow.com/v1/workspaces' with parameters offset=" + offset + " and limit=" + limit

            # Use the provided URL
            API_ENDPOINT = url
        
        # Set up the headers for the API request
        DEFINE HEADERS
          SET "x-oneflow-api-token" IN HEADERS TO user.apiToken
          SET "x-oneflow-user-email" IN HEADERS TO user.email
          SET "Content-Type" IN HEADERS TO "application/json"
        
        # Send an HTTP GET request to the API endpoint
        response = Send GET Request to API_ENDPOINT using HEADERS with SSL Verification Enabled
        
        # Check the response status code
        IF response.StatusCode EQUALS 200 THEN
            jsonResponse = Parse response to JSON Format
            RETURN jsonResponse
        ELSE
            THROW HttpResponseError
    END

Oneflow Templates

End users can create Oneflow templates only through the Oneflow application, as the functionality to create templates is not currently supported through the Oneflow Public API. However, when creating a contract, users should be able to select the template to be used for the contract creation. To enable this, you can provide a list of available templates for users to choose from.

List of templates available for the user

Here, you can create your own front-end components to allow users to select the template for the contract creation process. For example, you can implement a dropdown menu to display and let users select the relevant template.

Get templates from Oneflow

To get the available templates for a particular user, you can use the Get Templates Oneflow Public API endpoint. Once the user has selected a workspace, you can display the list of templates available for that user in the selected workspace. Additionally, users can enable or disable templates from the Oneflow application. Therefore, you should filter out only the active templates and sort them by their names. Moreover, a template can be assigned to a template group of a particular extension (integration). When retrieving the list of templates, you should filter out those that belong to your extension (integration).

Below, you can find the pseudo code to get the templates the user has access to in a particular workspace.

FUNCTION GetTemplates
    INPUT: user
    OUTPUT: jsonResponse

    BEGIN
        # Initialize OneflowPublicAPI with authentication details
        Validate request
        user = user  # get user's Oneflow Token and Email from authentication table in your DB
        
        TRY
            # Fetch templates with specified criteria
            # Ensure workspace_ids is a list for the function call
            templates = Get Paginated Template using user and Workspace IDs using GetPaginatedTemplate 
        CATCH Exception
            Handle the exception

        # Prepare the response data structure with template IDs and names
        Initialize templates_response with an empty list
        FOR EACH Template IN Templates
            # Create a dictionary for each template with ID and Name
            Template_info = Create dictionary with ID and Name from Template
            ADD Template_info TO Templates_response

        # Convert the response data to JSON format and return it
        RETURN Jsonify(Templates_response)
    END

The Oneflow Public API allows you to retrieve a maximum of 100 templates at a time. Therefore, you must use pagination to fetch all the templates from Oneflow.

FUNCTION GetPaginatedTemplate
    INPUT: user (includes API token and email), workspace_ids
    OUTPUT: List of Workspaces with Permission

    BEGIN
        Initialize templates as an empty list
        Initialize next_link as None
        
        LOOP FOREVER
            # Step 1: Fetch templates starting from the initial or next link
            selected_templates = Get Oneflow Templates using user, next_link, and workspace_ids using GetOneflowTemplates
            # Extract the list of actual templates from the 'data' field of selected_templates, which contains the templates details
            selected_templates_data = Extract data from selected_templates
            
            # Step 2: Update next_link to point to the next set of templates, if available
            SET next_link to the next URL from selected_templates
            IF next_link IS None THEN
                BREAK the loop

        # Step 4: Return the list of templates
        RETURN templates
    END

Here's a pseudo code function that demonstrates how to send a request to Oneflow using additional query parameters, incorporating pagination to handle fetching all available templates:

FUNCTION GetOneflowTemplates
    INPUT: user (includes API token and email), workspace_ids, url
    OUTPUT: jsonResponse

    BEGIN
        IF url IS None THEN
            # Define query parameters for fetching templates
            DEFINE query_params WITH
              offset SET TO '0',
              limit SET TO '100',
              filter[workspace_ids] SET TO Concatenate workspace_ids into a comma-separated string,
              filter[active] SET TO 'True',
              sort SET TO 'name',
              extension_type SET TO EXTENSION_TYPE

            # Define the API endpoint for templates with dynamic query parameters
            API_ENDPOINT = "Construct URL 'https://api.oneflow.com/v1/templates?' with query_params"
						
        ELSE
            # Use the provided URL for pagination or specific filters
            API_ENDPOINT = url
        
        # Set up the headers for the API request
        DEFINE HEADERS
          SET "x-oneflow-api-token" IN HEADERS TO user.apiToken
          SET "x-oneflow-user-email" IN HEADERS TO user.email
          SET "Content-Type" IN HEADERS TO "application/json"
           
        # Send an HTTP GET request to the API endpoint
        response = Send GET Request to API_ENDPOINT using HEADERS with SSL Verification Enabled
        
        # Check the response status code
        IF response.StatusCode EQUALS 200 THEN
            jsonResponse = Parse response to JSON Format
            RETURN jsonResponse
        ELSE
            THROW HttpResponseError
    END

As a developer, if you have any doubts about the EXTENSION_TYPE of your extension (integration), you can send a GET request to the Get Integration Extensions endpoint to retrieve all the available extensions in a Oneflow account. This allows you to identify your extension type from the response.

Once your user has selected both the workspace and the template for creating the contract, if you need to obtain more details about the template before creating the contract, you can use the Get a Template by ID endpoint to access more details of the selected template.

Contract Participants

Contract participants are a crucial entity in a contract. Therefore, you can enable your users to add available contract owner-side participants and counter-participants to a particular contract from your system.

For more details about managing participants according to the integration category you are implementing, please follow the relevant documents below:

Contract Data Fields

Contract Data fields are an important aspect that can be used as contract variables that you can use in contract product tables, text, and form sections. With these data fields, you can map or send values of some entities in your system to the Oneflow contract.

To get more knowledge about data fields, you can follow this section in the Oneflow Public API documentation. Such that you have to create a template group with data fields in the Configure Template group and Webhook, and use those data fields in that template group as variables to sync data from your system to the Oneflow contract and vice versa.